or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-babel-preset-gatsby-package

Babel preset used for internal Gatsby packages, providing JavaScript/TypeScript compilation with browser and Node.js environment targeting

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/babel-preset-gatsby-package@3.15.x

To install, run

npx @tessl/cli install tessl/npm-babel-preset-gatsby-package@3.15.0

index.mddocs/

Babel Preset Gatsby Package

Babel preset used for internal Gatsby packages, providing JavaScript/TypeScript compilation with browser and Node.js environment targeting. This preset configures a comprehensive compilation pipeline with modern JavaScript features, React JSX, Flow types, TypeScript support, and custom Gatsby-specific transformations.

Package Information

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

Core Imports

const preset = require("babel-preset-gatsby-package");

For use in Babel configuration:

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

Basic Usage

Simple Configuration

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

With Options

{
  "presets": [
    ["babel-preset-gatsby-package", {
      "browser": true,
      "nodeVersion": "18.0.0",
      "debug": false,
      "esm": true
    }]
  ]
}

Programmatic Usage

const preset = require("babel-preset-gatsby-package");

const config = preset(null, {
  browser: true,
  debug: true,
  nodeVersion: "16.0.0",
  availableCompilerFlags: ["GATSBY_MAJOR", "CUSTOM_FLAG"],
  keepDynamicImports: ["/path/to/file.js"]
});

Architecture

The preset configures the following Babel components:

  • Environment Targeting: @babel/preset-env with configurable browser/Node.js targets
  • React Support: @babel/preset-react for JSX transformation
  • Type Support: @babel/preset-flow for Flow annotations and TypeScript plugin for .ts/.tsx files
  • Modern JavaScript: Plugins for optional chaining, nullish coalescing, and dynamic imports
  • Runtime Optimization: @babel/plugin-transform-runtime for efficient polyfills
  • Custom Transformations: Gatsby-specific compiler flags and dynamic import preservation
  • Lodash Optimization: Automatic import optimization for lodash usage

Capabilities

Preset Configuration

Main preset factory function that generates Babel configuration based on target environment and options.

/**
 * Creates Babel configuration for internal Gatsby packages
 * @param {object} context - Babel context (typically unused)
 * @param {PresetOptions} options - Configuration options
 * @returns {BabelConfig} Complete Babel configuration object
 */
function preset(context, options = {});

interface PresetOptions {
  /** Target browser environment instead of Node.js (default: false) */
  browser?: boolean;
  /** Enable debug output for preset-env (default: false) */
  debug?: boolean;
  /** Node.js version to target (default: "18.0.0") */
  nodeVersion?: string;
  /** Output ES modules instead of CommonJS (default: false) */
  esm?: boolean;
  /** Available compiler flags for conditional compilation (default: ["GATSBY_MAJOR"]) */
  availableCompilerFlags?: string[];
  /** File paths where dynamic imports should be preserved (default: null) */
  keepDynamicImports?: string[] | null;
}

interface BabelConfig {
  /** Array of Babel presets with configuration */
  presets: Array<string | [string, object]>;
  /** Array of Babel plugins with configuration */
  plugins: Array<string | [string, object] | false>;
  /** File-specific overrides for TypeScript/TSX */
  overrides: Array<{
    test: string[];
    plugins: Array<[string, object]>;
  }>;
}

Environment Configuration

The preset automatically configures different targeting modes:

Browser Mode (browser: true):

  • Targets modern browsers with configurable ES module support
  • Uses esmodules: true when esm: true
  • Falls back to legacy browser support otherwise

Node.js Mode (default):

  • Targets specified Node.js version (default: 18.0.0)
  • Enables CoreJS polyfills with entry mode
  • Uses CommonJS modules unless esm: true

Compiler Flags

Custom build-time constant replacement system using the COMPILER_OPTIONS environment variable.

// Environment variable format: "KEY=value,KEY2=value2"
// Default: COMPILER_OPTIONS="GATSBY_MAJOR=5"

// In source code, compiler flags are replaced:
const version = _CFLAGS_.GATSBY_MAJOR; // becomes "5" at build time

Environment Variables:

  • COMPILER_OPTIONS: Comma-separated key=value pairs for compiler flags
  • NODE_ENV / BABEL_ENV: Controls test environment behavior
  • When NODE_ENV or BABEL_ENV equals "test", enables babel-plugin-dynamic-import-node

Dynamic Import Preservation

Controls whether dynamic imports are transformed or preserved for specific files.

// Configuration
{
  keepDynamicImports: ["/absolute/path/to/file.js", "/another/file.js"]
}

// In preserved files, dynamic imports remain untransformed:
const module = import("./dynamic-module"); // stays as-is

Included Babel Presets

@babel/preset-env

Configured with:

  • Loose mode: Enabled for performance
  • Shipped proposals: Enabled for modern features
  • Bugfixes: Enabled when using ESM
  • Modules: CommonJS (default) or false for ESM
  • Target-specific configuration: Browser or Node.js targets

@babel/preset-react

Configured for JSX transformation with default settings.

@babel/preset-flow

Configured for Flow type annotation removal.

Included Babel Plugins

Standard Plugins

// Always included plugins:
"@babel/plugin-proposal-nullish-coalescing-operator"
"@babel/plugin-proposal-optional-chaining"
"@babel/plugin-transform-runtime" 
"@babel/plugin-syntax-dynamic-import"
"@sigmacomputing/babel-plugin-lodash"

// Test environment only:
"babel-plugin-dynamic-import-node" // when NODE_ENV/BABEL_ENV === "test"

Custom Plugins

babel-transform-compiler-flags

Replaces _CFLAGS_.FLAGNAME expressions with string literals based on COMPILER_OPTIONS.

// Plugin configuration
[
  "./babel-transform-compiler-flags",
  {
    flags: { GATSBY_MAJOR: "5" }, // from COMPILER_OPTIONS
    availableFlags: ["GATSBY_MAJOR"] // from preset options
  }
]

babel-transform-mark-to-keep-dynamic-import

Preserves dynamic imports in specified files by preventing their transformation.

// Plugin configuration (when keepDynamicImports is provided)
[
  "./babel-transform-mark-to-keep-dynamic-import", 
  {
    keepDynamicImports: ["/absolute/path/to/file.js"]
  }
]

TypeScript Support

Automatic TypeScript/TSX compilation through file-specific overrides:

// Override configuration for .ts/.tsx files
{
  test: ["**/*.ts", "**/*.tsx"],
  plugins: [["@babel/plugin-transform-typescript", { isTSX: true }]]
}

Usage Examples

Development Build

{
  "presets": [
    ["babel-preset-gatsby-package", {
      "debug": true,
      "nodeVersion": "18.0.0"
    }]
  ]
}

Browser Production Build

{
  "presets": [
    ["babel-preset-gatsby-package", {
      "browser": true,
      "esm": true
    }]
  ]
}

Custom Compiler Flags

# Set environment variable
export COMPILER_OPTIONS="GATSBY_MAJOR=5,CUSTOM_FLAG=production"
{
  "presets": [
    ["babel-preset-gatsby-package", {
      "availableCompilerFlags": ["GATSBY_MAJOR", "CUSTOM_FLAG"]
    }]
  ]
}

Preserve Dynamic Imports

{
  "presets": [
    ["babel-preset-gatsby-package", {
      "keepDynamicImports": [
        "/app/src/dynamic-loader.js",
        "/app/src/lazy-components.js"
      ]
    }]
  ]
}