CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-babel-preset-gatsby-package

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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"
      ]
    }]
  ]
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/babel-preset-gatsby-package@3.15.x
Publish Source
CLI
Badge
tessl/npm-babel-preset-gatsby-package badge