CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-rollup-plugin-esbuild

A Rollup plugin that uses esbuild as a fast TypeScript/JavaScript compiler and minifier, replacing traditional tools like rollup-plugin-typescript2 and rollup-plugin-terser

—

Pending
Overview
Eval results
Files

dependency-optimization.mddocs/

Dependency Optimization

The experimental dependency optimization feature provides pre-bundling capabilities for external dependencies using esbuild's fast bundling engine, eliminating the need for additional CommonJS and Node.js resolution plugins.

Capabilities

Dependency Optimization Configuration

Configure which dependencies should be pre-bundled and optimized during the build process.

interface OptimizeDepsOptions {
  /** List of dependency names to include in optimization */
  include: string[];
  /** List of dependency names to exclude from optimization */
  exclude?: string[];
  /** Working directory for dependency resolution */
  cwd: string;
  /** Additional esbuild options for the optimization build */
  esbuildOptions?: EsbuildBuildOptions;
  /** Enable source map generation for optimized dependencies */
  sourceMap: boolean;
}

interface OptimizeDepsResult {
  /** Map of optimized dependencies to their bundled file paths */
  optimized: Map<string, { file: string }>;
  /** Directory where optimized dependencies are cached */
  cacheDir: string;
}

// Re-exported from esbuild for reference
interface EsbuildBuildOptions {
  entryPoints?: string[];
  bundle?: boolean;
  splitting?: boolean;
  format?: "iife" | "cjs" | "esm";
  target?: string | string[];
  outdir?: string;
  outfile?: string;
  platform?: "browser" | "node" | "neutral";
  external?: string[];
  loader?: { [ext: string]: Loader };
  define?: { [key: string]: string };
  inject?: string[];
  banner?: { [type: string]: string };
  footer?: { [type: string]: string };
  metafile?: boolean;
  write?: boolean;
  plugins?: any[];
}

Usage Examples:

import esbuild from "rollup-plugin-esbuild";

// Basic dependency optimization
export default {
  plugins: [
    esbuild({
      optimizeDeps: {
        include: ["react", "react-dom"]
      }
    })
  ]
};

// Advanced optimization with exclusions
export default {
  plugins: [
    esbuild({
      optimizeDeps: {
        include: ["lodash", "moment", "axios"],
        exclude: ["moment/locale/*"],
        esbuildOptions: {
          target: "es2020",
          format: "esm"
        }
      }
    })
  ]
};

// Optimization with custom esbuild options
export default {
  plugins: [
    esbuild({
      optimizeDeps: {
        include: ["vue", "vue-router"],
        esbuildOptions: {
          define: {
            "process.env.NODE_ENV": '"production"'
          },
          external: ["node:*"]
        }
      }
    })
  ]
};

Include Dependencies

Specify which dependencies should be optimized and pre-bundled.

interface IncludeOptions {
  /** Array of dependency names to optimize */
  include: string[];
}

Behavior:

  • Dependencies are resolved from node_modules
  • Each dependency is bundled into a single optimized file
  • Optimized files are cached in node_modules/.optimize_deps
  • Supports both bare module names and scoped packages

Examples:

{
  include: [
    "react",              // Regular package
    "react-dom",          
    "@babel/core",        // Scoped package
    "lodash/debounce"     // Specific export
  ]
}

Exclude Dependencies

Specify dependencies that should be excluded from optimization even if they're dependencies of included packages.

interface ExcludeOptions {
  /** Array of dependency names to exclude from optimization */
  exclude?: string[];
}

Usage:

{
  include: ["react", "react-dom"],
  exclude: [
    "react-dom/server",   // Exclude server-side rendering
    "react/jsx-dev-runtime" // Exclude development runtime
  ]
}

Cache Directory

The optimization process creates a cache directory for optimized dependencies.

interface CacheInfo {
  /** Default cache directory location */
  cacheDir: string; // "node_modules/.optimize_deps"
}

Behavior:

  • Cache directory is automatically created
  • Contains bundled versions of optimized dependencies
  • Files are named after the dependency (e.g., react.js, vue.js)
  • Cache is persistent across builds for performance

Custom ESBuild Options

Provide additional esbuild configuration for the optimization build process.

interface OptimizationBuildOptions {
  /** Additional esbuild options for optimization */
  esbuildOptions?: {
    /** Target environment for optimized code */
    target?: string | string[];
    /** Output format for optimized bundles */
    format?: "esm" | "cjs";
    /** Global replacements for optimized code */
    define?: { [key: string]: string };
    /** External dependencies that shouldn't be bundled */
    external?: string[];
    /** Custom loaders for specific file types */
    loader?: { [ext: string]: Loader };
    /** Code injection for polyfills or setup */
    inject?: string[];
    /** Platform-specific optimizations */
    platform?: "browser" | "node" | "neutral";
  };
}

Common configurations:

// Browser-optimized dependencies
{
  esbuildOptions: {
    target: ["es2020", "chrome80"],
    format: "esm",
    platform: "browser",
    define: {
      "process.env.NODE_ENV": '"production"'
    }
  }
}

// Node.js optimized dependencies
{
  esbuildOptions: {
    target: "node16",
    format: "cjs",
    platform: "node",
    external: ["node:*"]
  }
}

Integration with Rollup Build

The optimization integrates seamlessly with the Rollup build process through plugin lifecycle hooks.

interface OptimizationLifecycle {
  /** Runs during buildStart phase */
  buildStart(): Promise<void>;
  /** Intercepts module resolution */
  resolveId(id: string, importer?: string): string | null;
}

Behavior:

  • Optimization runs once during buildStart
  • Optimized dependencies are resolved to their cached versions
  • No changes required to import statements in source code
  • Works transparently with existing Rollup configuration

Performance Benefits

Dependency optimization provides several performance improvements:

Build Time Benefits:

  • Pre-bundled dependencies reduce individual file processing
  • Eliminates need for CommonJS transformation of dependencies
  • Reduces module resolution overhead during build

Runtime Benefits:

  • Fewer HTTP requests for dependency files
  • Optimized and minified dependency code
  • Better tree-shaking of unused dependency code

Bundle Size Benefits:

  • Dead code elimination across dependency boundaries
  • Optimized imports and exports
  • Reduced duplication between dependencies

Limitations and Considerations

Experimental Status:

  • Feature is marked as experimental
  • Breaking changes may occur in minor versions
  • Not recommended for production use without thorough testing

Compatibility:

  • Some packages may not work correctly when pre-bundled
  • Dynamic imports within dependencies may be affected
  • Native Node.js modules cannot be optimized

Troubleshooting:

  • Use exclude option for problematic dependencies
  • Check generated cache files for bundling issues
  • Monitor build output for optimization warnings

Install with Tessl CLI

npx tessl i tessl/npm-rollup-plugin-esbuild

docs

dependency-optimization.md

index.md

main-plugin.md

minification.md

tile.json