tessl/npm-metro-transform-worker

Transform worker for Metro bundler that handles JavaScript, TypeScript, JSX, JSON, and asset transformations through a comprehensive Babel-based pipeline.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration System

Name: tessl/npm-metro-transform-worker
Author: tessl

Metro Transform Worker's comprehensive configuration system allows fine-tuned control over Babel transformations, asset processing, minification, and optimization behavior.

Capabilities

Transformer Configuration

Main configuration object that controls all aspects of the transformation pipeline.

interface JsTransformerConfig {
  /** Array of asset plugin module paths for custom asset processing */
  assetPlugins: ReadonlyArray<string>;
  /** Path to asset registry module (typically React Native's AssetRegistry) */
  assetRegistryPath: string;
  /** Path to async require module for dynamic imports */
  asyncRequireModulePath: string;
  /** Absolute path to Babel transformer module */
  babelTransformerPath: string;
  /** Behavior for dynamic requires in node_modules packages */
  dynamicDepsInPackages: DynamicRequiresBehavior;
  /** Enable .babelrc file lookup during transformation */
  enableBabelRCLookup: boolean;
  /** Enable Babel runtime helpers (true/false or runtime module path) */
  enableBabelRuntime: boolean | string;
  /** Global prefix for Metro-generated variables */
  globalPrefix: string;
  /** Use Hermes parser instead of Babylon */
  hermesParser: boolean;
  /** Configuration object passed to minifier */
  minifierConfig: MinifierConfig;
  /** Absolute path to minifier module */
  minifierPath: string;
  /** File size limit for applying optimizations (bytes) */
  optimizationSizeLimit: number;
  /** Public path for serving assets */
  publicPath: string;
  /** How to handle optional dependencies */
  allowOptionalDependencies: AllowOptionalDependencies;
  /** Path to custom dependency collection module */
  unstable_collectDependenciesPath: string;
  /** Reserved name for dependency map variable */
  unstable_dependencyMapReservedName?: string;
  /** Disable CommonJS module wrapping */
  unstable_disableModuleWrapping: boolean;
  /** Disable pseudo-global normalization optimization */
  unstable_disableNormalizePseudoGlobals: boolean;
  /** Generate compact output without extra whitespace */
  unstable_compactOutput: boolean;
  /** Enable require.context support for dynamic imports */
  unstable_allowRequireContext: boolean;
  /** Enable memoization for inline requires */
  unstable_memoizeInlineRequires?: boolean;
  /** Module specifiers to exclude from inline require memoization */
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
  /** Rename scoped require functions to avoid conflicts */
  unstable_renameRequire?: boolean;
}

Usage Examples:

// Basic React Native configuration
const config = {
  assetPlugins: [],
  assetRegistryPath: "react-native/Libraries/Image/AssetRegistry",
  asyncRequireModulePath: "metro-runtime/src/modules/asyncRequire",
  babelTransformerPath: require.resolve("@react-native/metro-babel-transformer"),
  dynamicDepsInPackages: "throwAtRuntime",
  enableBabelRCLookup: true,
  enableBabelRuntime: false,
  globalPrefix: "",
  hermesParser: false,
  minifierConfig: {
    output: {
      ascii_only: true,
      quote_style: 3,
      wrap_iife: true,
    },
    sourceMap: {
      includeSources: false,
    },
    toplevel: false,
    compress: {
      reduce_funcs: false,
    },
  },
  minifierPath: require.resolve("metro-minify-terser"),
  optimizationSizeLimit: 150000,
  publicPath: "/assets",
  allowOptionalDependencies: "ignore",
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
  unstable_disableModuleWrapping: false,
  unstable_compactOutput: false,
  unstable_allowRequireContext: false,
};

// Web development configuration
const webConfig = {
  ...config,
  assetRegistryPath: "metro-runtime/src/modules/assetRegistry",
  enableBabelRuntime: "@babel/runtime",
  publicPath: "/static/assets/",
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
  unstable_compactOutput: true,
  unstable_allowRequireContext: true,
};

// Development configuration with optimizations disabled
const devConfig = {
  ...config,
  enableBabelRCLookup: false,
  optimizationSizeLimit: 0, // Disable size-based optimizations
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
  unstable_disableNormalizePseudoGlobals: true,
};

Transform Options

Per-transformation options that control behavior for individual files.

interface JsTransformOptions {
  /** Custom transformation options passed to Babel transformer */
  customTransformOptions?: CustomTransformOptions;
  /** Development mode (affects optimizations and debugging features) */
  dev: boolean;
  /** Enable experimental ES6 import/export support */
  experimentalImportSupport?: boolean;
  /** Hot reloading support */
  hot: boolean;
  /** Inline platform-specific code branches */
  inlinePlatform: boolean;
  /** Inline require calls for performance */
  inlineRequires: boolean;
  /** Enable minification */
  minify: boolean;
  /** Module specifiers to exclude from inline requires */
  nonInlinedRequires?: ReadonlyArray<string>;
  /** Target platform (ios, android, web, etc.) */
  platform?: string;
  /** Runtime bytecode version for Hermes compilation */
  runtimeBytecodeVersion?: number;
  /** File type being transformed */
  type: Type;
  /** Disable ES6 to ES5 transformations */
  unstable_disableES6Transforms?: boolean;
  /** Enable memoization for inline requires */
  unstable_memoizeInlineRequires?: boolean;
  /** Module specifiers to exclude from memoization */
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
  /** Enable static Hermes-optimized require calls */
  unstable_staticHermesOptimizedRequire?: boolean;
  /** Transformation profile for target runtime */
  unstable_transformProfile: TransformProfile;
}

Usage Examples:

// Development options
const devOptions = {
  dev: true,
  hot: true,
  inlinePlatform: false,
  inlineRequires: false,
  minify: false,
  platform: "ios",
  type: "module",
  unstable_transformProfile: "default",
};

// Production options with optimizations
const prodOptions = {
  dev: false,
  hot: false,
  inlinePlatform: true,
  inlineRequires: true,
  minify: true,
  nonInlinedRequires: ["react", "react-native"],
  platform: "ios",
  type: "module",
  unstable_transformProfile: "default",
};

// Hermes-optimized options
const hermesOptions = {
  ...prodOptions,
  runtimeBytecodeVersion: 74, // Hermes bytecode version
  unstable_staticHermesOptimizedRequire: true,
  unstable_transformProfile: "hermes-stable",
};

// Web bundle options
const webOptions = {
  dev: false,
  experimentalImportSupport: true,
  inlinePlatform: true,
  inlineRequires: true,
  minify: true,
  platform: "web",
  type: "module",
  unstable_disableES6Transforms: false,
  unstable_transformProfile: "default",
};

Configuration Types

Dynamic Dependencies Behavior

type DynamicRequiresBehavior = "reject" | "throwAtRuntime";

"reject": Reject dynamic requires at build time (strict mode)
"throwAtRuntime": Allow in node_modules but throw at runtime for app code

Transform Profiles

type TransformProfile = "default" | "hermes-stable" | "hermes-canary";

"default": Standard JavaScript transformation for V8/JSC
"hermes-stable": Optimizations for stable Hermes engine
"hermes-canary": Optimizations for experimental Hermes features

File Types

type Type = "script" | "module" | "asset";

"script": Standalone script (no module wrapping)
"module": CommonJS/ES6 module (standard bundling)
"asset": Static asset (images, fonts, etc.)

Optional Dependencies Handling

type AllowOptionalDependencies = "ignore" | "reject";

"ignore": Skip missing optional dependencies
"reject": Fail build on missing optional dependencies

Minifier Configuration

The minifier configuration is passed directly to the configured minifier (typically Terser):

interface MinifierConfig {
  /** Output formatting options */
  output?: {
    /** Generate ASCII-only output */
    ascii_only?: boolean;
    /** Quote style for string literals */
    quote_style?: number;
    /** Wrap immediately invoked function expressions */
    wrap_iife?: boolean;
  };
  /** Source map generation options */
  sourceMap?: {
    /** Include original source code in source maps */
    includeSources?: boolean;
  };
  /** Enable top-level variable mangling */
  toplevel?: boolean;
  /** Compression/optimization options */
  compress?: {
    /** Reduce function expressions to function declarations */
    reduce_funcs?: boolean;
  };
}

Custom Transform Options

Extended options for specific Babel transformers and Metro features:

interface CustomTransformOptions {
  /** Enable static Hermes-optimized require calls */
  unstable_staticHermesOptimizedRequire?: boolean;
  /** Custom Babel transformer-specific options */
  [key: string]: any;
}