CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-parcel--transformer-babel

A Parcel transformer plugin that transforms JavaScript code using Babel with automatic configuration discovery and intelligent defaults for modern JavaScript, TypeScript, JSX, and Flow.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

configuration.mddocs/

Configuration Management

Babel configuration loading, validation, and default configuration generation with automatic dependency detection and performance optimization warnings.

Capabilities

Configuration Loading

Main function for loading and processing Babel configuration from the filesystem or building intelligent defaults.

/**
 * Loads Babel configuration for the current asset
 * Discovers filesystem configs or builds default configuration
 * @param config - Parcel configuration object
 * @param options - Plugin options
 * @param logger - Plugin logger for warnings and errors
 * @returns Promise resolving to BabelConfigResult or null if no transformation needed
 */
export async function load(
  config: Config,
  options: PluginOptions,
  logger: PluginLogger
): Promise<BabelConfigResult | null>;

interface BabelConfigResult {
  internal: boolean;           // True if using default config, false for filesystem config
  config: BabelConfig;         // The actual Babel configuration
  targets?: mixed;             // Babel targets for preset-env
  syntaxPlugins?: mixed;       // Additional syntax plugins to enable
}

interface BabelConfig {
  plugins?: Array<any>;        // Babel plugins array
  presets?: Array<any>;        // Babel presets array
}

Configuration Discovery Process:

  1. Skip Non-Source Files: Returns null for files in node_modules
  2. File Invalidation Setup: Watches for Babel config file creation
  3. Config Resolution: Searches for existing Babel configuration files
  4. Fallback to Defaults: Uses buildDefaultBabelConfig if no config found
  5. Babel Core Loading: Loads and validates @babel/core dependency
  6. Environment Setup: Configures BABEL_ENV and NODE_ENV handling
  7. Partial Config Loading: Uses Babel's loadPartialConfigAsync
  8. Dependency Tracking: Tracks config files for invalidation
  9. Performance Warnings: Warns about non-optimal configurations
  10. Cache Key Generation: Creates cache keys for configuration

Default Configuration Builder

Builds intelligent default Babel configuration when no filesystem config is found.

/**
 * Builds default Babel configuration for files without explicit config
 * Primarily handles Flow type stripping with JSX support
 * @param options - Plugin options
 * @param config - Parcel configuration object
 * @returns Promise resolving to BabelConfigResult or null if no config needed
 */
async function buildDefaultBabelConfig(
  options: PluginOptions,
  config: Config
): Promise<BabelConfigResult | null>;

Default Configuration Logic:

  • TypeScript Files: Returns null (handled by TypeScript transformer)
  • Flow Detection: Enables Flow type stripping if flow-bin dependency found
  • JSX Support: Adds JSX syntax plugin when React-like dependencies detected
  • Minimal Configuration: Only applies necessary transformations

Usage Example:

// Internal usage - called when no filesystem config found
const defaultConfig = await buildDefaultBabelConfig(pluginOptions, parcelConfig);

// Typical default config for Flow + JSX file:
// {
//   internal: true,
//   config: {
//     plugins: [
//       ['@babel/plugin-transform-flow-strip-types', { requireDirective: true }]
//     ]
//   },
//   syntaxPlugins: ['jsx']
// }

Supported Configuration Files

The configuration system recognizes all standard Babel configuration file formats:

const BABEL_CONFIG_FILENAMES = [
  '.babelrc',
  '.babelrc.js',
  '.babelrc.json', 
  '.babelrc.cjs',
  '.babelrc.mjs',
  '.babelignore',
  'babel.config.js',
  'babel.config.json',
  'babel.config.mjs',
  'babel.config.cjs'
];

Plugin Dependency Management

Tracks and manages Babel plugin and preset dependencies for proper invalidation.

/**
 * Defines plugin dependencies for cache invalidation
 * @param config - Parcel configuration object
 * @param babelConfig - Babel configuration with plugins/presets
 * @param options - Plugin options
 */
function definePluginDependencies(
  config: Config,
  babelConfig: BabelConfig | null,
  options: PluginOptions
): void;

Dependency Tracking Features:

  • Adds dev dependencies for all used plugins and presets
  • Configures additional invalidations for @babel/core
  • Ensures cache invalidation when plugins or dependencies update
  • Handles relative path resolution from project root

Configuration Validation

Detects problematic configurations and provides performance warnings.

/**
 * Warns about redundant presets that may impact performance
 * @param fs - File system interface
 * @param babelConfig - Loaded Babel configuration
 * @param logger - Plugin logger for warnings
 */
async function warnOnRedundantPlugins(
  fs: FileSystem,
  babelConfig: PartialConfig,
  logger: PluginLogger
): Promise<void>;

Redundant Presets Detection:

  • @babel/preset-env (conflicts with Parcel's builtin transpilation)
  • @babel/preset-react (handled automatically)
  • @babel/preset-typescript (conflicts with TypeScript transformer)
  • @parcel/babel-preset-env (Parcel-specific alternative)

Performance Warnings:

  • JavaScript Config Files: Warns about non-cacheable JS config files
  • Runtime Requires: Warns about require() calls in configuration
  • Redundant Presets: Suggests removing unnecessary presets
  • Target Incompatibility: Warns about @babel/preset-env target conflicts

Environment Configuration

Handles Babel environment variables and mode configuration.

// Environment variables monitored for invalidation
config.invalidateOnEnvChange('BABEL_ENV');
config.invalidateOnEnvChange('NODE_ENV');

// Environment name resolution priority:
// 1. BABEL_ENV environment variable
// 2. NODE_ENV environment variable  
// 3. Parcel mode (if 'production' or 'development')
// 4. Default to 'development'

Usage Examples:

// Typical configuration loading flow
const configResult = await load(parcelConfig, pluginOptions, logger);

if (configResult) {
  console.log('Config type:', configResult.internal ? 'default' : 'filesystem');
  console.log('Babel config:', configResult.config);
  console.log('Targets:', configResult.targets);
  console.log('Syntax plugins:', configResult.syntaxPlugins);
}

// Example filesystem config result:
// {
//   internal: false,
//   config: {
//     presets: [['@babel/preset-env', { targets: { node: '16' } }]],
//     plugins: ['@babel/plugin-proposal-class-properties']
//   },
//   targets: { node: '16.0.0' },
//   syntaxPlugins: ['jsx']
// }

Configuration Caching

  • Static Configs: JSON/RC files are cached based on content hash
  • Dynamic Configs: JS config files invalidate on startup
  • Dependency Tracking: Plugin/preset changes trigger re-compilation
  • Environment Sensitivity: BABEL_ENV/NODE_ENV changes invalidate cache

Error Handling

  • Missing Dependencies: Automatic installation with shouldAutoInstall flag
  • Invalid Configurations: Clear error messages with file context
  • Version Conflicts: Warnings for incompatible @babel/core versions
  • File Permission Issues: Graceful handling of unreadable config files

Install with Tessl CLI

npx tessl i tessl/npm-parcel--transformer-babel

docs

babel-processing.md

configuration.md

error-handling.md

index.md

transformer.md

utilities.md

tile.json