or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Gulp Load Plugins

Gulp Load Plugins automatically loads any gulp plugins from package.json dependencies and attaches them to a configurable object. It eliminates the need for manual require() statements for each gulp plugin by scanning package dependencies, filtering for gulp-prefixed packages, and creating a plugins object with camelCase property names.

Package Information

Package Name: gulp-load-plugins
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev gulp-load-plugins
Node.js Requirements: Node.js >= 8.0.0

Core Imports

const gulpLoadPlugins = require('gulp-load-plugins');
const plugins = gulpLoadPlugins();

Or more concisely:

const plugins = require('gulp-load-plugins')();

Basic Usage

Given a package.json with gulp plugin dependencies:

{
  "dependencies": {
    "gulp-jshint": "*",
    "gulp-concat": "*",
    "gulp-uglify": "*"
  }
}

Load all plugins automatically:

const gulp = require('gulp');
const plugins = require('gulp-load-plugins')();

// Now you can use plugins without requiring them individually
gulp.task('scripts', () => {
  return gulp.src('src/**/*.js')
    .pipe(plugins.jshint())
    .pipe(plugins.concat('app.js'))
    .pipe(plugins.uglify())
    .pipe(gulp.dest('dist'));
});

This is equivalent to manually requiring each plugin:

const jshint = require('gulp-jshint');
const concat = require('gulp-concat');
const uglify = require('gulp-uglify');

Capabilities

Plugin Loading Function

The main export is a function that scans package.json dependencies and returns an object with lazy-loaded gulp plugins.

/**
 * Loads gulp plugins from package dependencies and attaches them to an object
 * @param {LoadPluginsOptions} options - Configuration options
 * @returns {object} Object with plugin properties that load on first access
 */
function gulpLoadPlugins(options);

Configuration Options

All configuration options are optional and have sensible defaults.

interface LoadPluginsOptions {
  /** Enable debug logging to console (default: false) */
  DEBUG?: boolean;
  
  /** Glob patterns to search for plugins (default: ['gulp-*', 'gulp.*', '@*/gulp{-,.}*']) */
  pattern?: string | string[];
  
  /** When true, overrides built-in patterns; when false, extends them (default: true) */
  overridePattern?: boolean;
  
  /** Path to package.json or config object (default: auto-discovered from current working directory) */
  config?: string | object;
  
  /** Which dependency sections to scan (default: ['dependencies', 'devDependencies', 'peerDependencies']) */
  scope?: string | string[];
  
  /** Pattern to remove from plugin names (default: /^gulp(-|\.)/) */
  replaceString?: RegExp;
  
  /** Transform hyphenated names to camelCase (default: true) */
  camelize?: boolean;
  
  /** Whether plugins should be lazy loaded on demand (default: true) */
  lazy?: boolean;
  
  /** Manual mapping for renaming specific plugins (default: {}) */
  rename?: { [pluginName: string]: string };
  
  /** Custom function for plugin name transformation */
  renameFn?: (name: string) => string;
  
  /** Transform functions applied after plugin loading (default: {}) */
  postRequireTransforms?: { [pluginName: string]: (plugin: any) => any };
  
  /** Keep scoped packages in nested objects vs flattened (default: true) */
  maintainScope?: boolean;
  
  /** Custom require function for loading plugins */
  requireFn?: (name: string) => any;
}

Common Usage Patterns

Basic Configuration

Most common configuration options:

const plugins = require('gulp-load-plugins')({
  DEBUG: false,              // Enable for troubleshooting
  lazy: true,               // Lazy load plugins (recommended)
  camelize: true,           // Convert hyphenated names to camelCase
  maintainScope: true       // Keep scoped packages nested
});

Custom Patterns

Override or extend the default plugin search patterns:

// Override default patterns completely
const plugins = require('gulp-load-plugins')({
  pattern: ['gulp-*', 'my-gulp-*'],
  overridePattern: true
});

// Extend default patterns
const plugins = require('gulp-load-plugins')({
  pattern: ['my-gulp-*'],
  overridePattern: false  // Adds to built-in patterns
});

Plugin Renaming

Rename plugins for cleaner access:

const plugins = require('gulp-load-plugins')({
  rename: {
    'gulp-ruby-sass': 'sass',
    'gulp-typescript': 'ts'
  }
});

// Access as plugins.sass and plugins.ts

Custom Name Transformation

Use a custom function for plugin name transformation:

const plugins = require('gulp-load-plugins')({
  renameFn: function(name) {
    // Custom logic to transform plugin names
    return name.replace(/^gulp-/, '').replace(/-(\w)/g, (m, p1) => p1.toUpperCase());
  }
});

Post-Require Transforms

Transform plugins after they're loaded:

const plugins = require('gulp-load-plugins')({
  postRequireTransforms: {
    sass: function(sass) {
      return sass.logError; // Return a specific method
    },
    foo: function(foo) {
      return foo.configure({ /* options */ });
    }
  }
});

Multiple Configuration Sources

Merge configurations from multiple package.json files:

const merge = require('lodash.merge');

const packages = merge(
  require('some-shared-config/package.json'),
  require('./package.json')
);

const plugins = require('gulp-load-plugins')({
  config: packages
});

Scoped Packages

Handle npm scoped packages:

// With maintainScope: true (default)
const plugins = require('gulp-load-plugins')();
// @mycompany/gulp-eslint becomes plugins.mycompany.eslint

// With maintainScope: false
const plugins = require('gulp-load-plugins')({
  maintainScope: false
});
// @mycompany/gulp-eslint becomes plugins.eslint

Plugin Name Resolution

The plugin name resolution follows these steps:

Pattern Matching: Find packages matching the configured patterns
Prefix Removal: Remove gulp prefix using replaceString pattern
Manual Rename: Apply any mappings from the rename option
Transform Function: Apply renameFn if provided
Camelization: Convert to camelCase if camelize is true
Scope Handling: Nest under scope object if maintainScope is true

Default Patterns

The default patterns match these plugin types:

gulp-*: Standard plugins (e.g., gulp-concat → concat)
gulp.*: Dot notation plugins (e.g., gulp.spritesmith → spritesmith)
@*/gulp{-,.}*: Scoped plugins (e.g., @myco/gulp-eslint → myco.eslint)

Note: The module automatically excludes gulp-load-plugins itself from being loaded to prevent circular references.

Name Examples

Package Name	Default Property	With maintainScope: false
`gulp-concat`	`plugins.concat`	`plugins.concat`
`gulp-ruby-sass`	`plugins.rubySass`	`plugins.rubySass`
`@angular/gulp-build`	`plugins.angular.build`	`plugins.build`
`gulp.spritesmith`	`plugins.spritesmith`	`plugins.spritesmith`

Error Handling

The function throws errors in these cases:

Missing Configuration: No package.json file found or config is null
Duplicate Names: Two plugins resolve to the same property name after transformation
Module Resolution: Plugin modules cannot be required/resolved

try {
  const plugins = require('gulp-load-plugins')({
    config: null
  });
} catch (error) {
  console.error(error.message); 
  // Throws: "Could not find dependencies. Do you have a package.json file in your project?"
}

Debugging

Enable debug mode to troubleshoot plugin loading:

const plugins = require('gulp-load-plugins')({
  DEBUG: true
});

// Console output will show:
// gulp-load-plugins: Debug enabled with options: {...}
// gulp-load-plugins: 15 plugin(s) found: gulp-concat gulp-uglify ...
// gulp-load-plugins: renaming gulp-concat to concat
// gulp-load-plugins: lazyload: adding property concat

Performance Considerations

Lazy Loading: Enabled by default, plugins are only required when first accessed
Pattern Efficiency: More specific patterns reduce scanning time
Scope Limitation: Use scope option to limit which dependency sections are scanned

// Optimize for performance
const plugins = require('gulp-load-plugins')({
  lazy: true,                    // Only load plugins when used
  scope: ['devDependencies'],    // Only scan dev dependencies
  pattern: ['gulp-*']           // Only match standard gulp plugins
});

Types

interface LoadPluginsOptions {
  DEBUG?: boolean;
  pattern?: string | string[];
  overridePattern?: boolean;
  config?: string | object;
  scope?: string | string[];
  replaceString?: RegExp;
  camelize?: boolean;
  lazy?: boolean;
  rename?: { [pluginName: string]: string };
  renameFn?: (name: string) => string;
  postRequireTransforms?: { [pluginName: string]: (plugin: any) => any };
  maintainScope?: boolean;
  requireFn?: (name: string) => any;
}

/**
 * Return type is a dynamic object where property names depend on the plugins found
 * and the configuration options applied. Each property contains the loaded plugin.
 */
interface PluginsObject {
  [pluginName: string]: any;
}