or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-gulp-rename

Gulp plugin for renaming files in build pipelines with flexible path transformation capabilities

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/gulp-rename@2.1.x

To install, run

npx @tessl/cli install tessl/npm-gulp-rename@2.1.0

Gulp Rename

Gulp rename is a Gulp plugin that provides flexible file renaming capabilities in build pipelines. It supports multiple renaming approaches including string paths, mutation functions, mapping functions, and configuration objects, enabling comprehensive path manipulation with built-in sourcemap handling.

Package Information

Package Name: gulp-rename
Package Type: npm
Language: JavaScript
Installation: npm install gulp-rename

Core Imports

const rename = require("gulp-rename");

Basic Usage

const gulp = require("gulp");
const rename = require("gulp-rename");

// Rename to a fixed path
gulp.src("./src/main/text/hello.txt")
  .pipe(rename("main/text/ciao/goodbye.md"))
  .pipe(gulp.dest("./dist"));

// Rename using configuration object
gulp.src("./src/**/hello.txt")
  .pipe(rename({
    dirname: "main/text/ciao",
    basename: "aloha", 
    prefix: "bonjour-",
    suffix: "-hola",
    extname: ".md"
  }))
  .pipe(gulp.dest("./dist"));

Capabilities

Main Rename Function

Creates a Transform stream that renames files based on the provided renaming parameter.

/**
 * Creates a Transform stream that renames files
 * @param {string|function|object} obj - Renaming parameter defining how files should be renamed
 * @param {object} [options] - Configuration options for the plugin
 * @returns {Stream.Transform} Transform stream that renames files
 * @throws {Error} "Unsupported renaming parameter type supplied" for invalid parameter types
 */
function gulpRename(obj, options);

String Parameter Renaming

Sets the output file path directly by replacing the entire relative path.

/**
 * @param {string} obj - Non-empty string defining the new file path
 */

Usage Example:

// Replace entire path
gulp.src("test/fixtures/hello.txt")
  .pipe(rename("hola.md"))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/hola.md

// Set relative path with directory globs
gulp.src("test/**/hello.txt") 
  .pipe(rename("fixtures/hola.md"))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/test/fixtures/hola.md

Function Parameter Renaming

Transforms paths using either mutating or mapping functions for dynamic renaming logic.

/**
 * @param {function} obj - Function that receives parsed path and file objects
 * @param {object} parsedPath - Object with dirname, basename, extname properties
 * @param {object} file - Complete vinyl file object with all file metadata
 * @returns {object|undefined} New path object (replaces parsedPath) or undefined (uses modified parsedPath)
 */

Mutating Function Usage:

// Modify path object in-place
gulp.src("./src/**/hello.txt")
  .pipe(rename(function (path) {
    path.dirname += "/ciao";
    path.basename += "-goodbye";
    path.extname = ".md";
  }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/main/text/ciao/hello-goodbye.md

Mapping Function Usage:

// Return completely new path object
gulp.src("./src/**/hello.txt")
  .pipe(rename(function (path) {
    return {
      dirname: path.dirname + "/ciao",
      basename: path.basename + "-goodbye",
      extname: ".md"
    };
  }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/main/text/ciao/hello-goodbye.md

Object Parameter Renaming

Declaratively configures path component replacements using a configuration object.

/**
 * @param {object} obj - Configuration object for path component replacements
 * @param {string} [obj.dirname] - Replaces the directory path
 * @param {string} [obj.prefix] - Prepends to the basename
 * @param {string} [obj.suffix] - Appends to the basename  
 * @param {string} [obj.basename] - Replaces the basename
 * @param {string} [obj.extname] - Replaces the file extension
 */

Usage Examples:

// Replace directory
gulp.src("test/**/hello.txt")
  .pipe(rename({ dirname: "elsewhere" }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/test/elsewhere/hello.txt

// Add prefix and suffix
gulp.src("test/**/hello.txt")
  .pipe(rename({ 
    prefix: "bonjour-",
    suffix: "-hola" 
  }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/test/fixtures/bonjour-hello-hola.txt

// Change extension
gulp.src("test/**/hello.txt")
  .pipe(rename({ extname: ".md" }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/test/fixtures/hello.md

// Remove directory (flatten)
gulp.src("test/**/hello.txt")
  .pipe(rename({ dirname: "" }))
  .pipe(gulp.dest("./dist"));
// Result: ./dist/test/hello.txt

Options Configuration

Optional configuration parameter that modifies plugin behavior.

/**
 * @param {object} [options] - Configuration options
 * @param {boolean} [options.multiExt=false] - Include multiple extensions in extname (e.g., ".min.js" instead of just ".js")
 */

Usage Example:

// Handle multiple extensions
gulp.src("test/fixtures/hello.min.txt")
  .pipe(rename({ basename: "goodbye" }, { multiExt: true }))
  .pipe(gulp.dest("./dist"));
// Without multiExt: goodbye.txt (basename: "hello.min", extname: ".txt")
// With multiExt: goodbye.min.txt (basename: "hello", extname: ".min.txt")

Types

/**
 * Path object structure used in function parameters
 */
interface ParsedPath {
  /** Directory path relative to base */
  dirname: string;
  /** Filename without extension */
  basename: string; 
  /** File extension including the dot */
  extname: string;
}

/**
 * Options object for configuring plugin behavior
 */
interface RenameOptions {
  /** Include multiple extensions in extname when true */
  multiExt?: boolean;
}

/**
 * Configuration object for declarative path renaming
 */
interface RenameConfig {
  /** Replaces the directory path */
  dirname?: string;
  /** Prepends to the basename */
  prefix?: string;
  /** Appends to the basename */
  suffix?: string;
  /** Replaces the basename */
  basename?: string;
  /** Replaces the file extension */
  extname?: string;
}

Error Handling

The plugin validates the renaming parameter and throws errors for unsupported types:

undefined: Throws "Unsupported renaming parameter type supplied"
null: Throws "Unsupported renaming parameter type supplied"
empty string: Throws "Unsupported renaming parameter type supplied"
boolean: Throws "Unsupported renaming parameter type supplied"
number: Throws "Unsupported renaming parameter type supplied"

// These will throw errors
gulp.src("test/**/hello.txt")
  .pipe(rename())          // undefined
  .pipe(rename(null))      // null
  .pipe(rename(""))        // empty string
  .pipe(rename(true))      // boolean
  .pipe(rename(123))       // number

Sourcemap Support

The plugin automatically handles sourcemaps when present. When a file has an associated sourcemap, the plugin updates the sourcemap's file property to match the renamed file's relative path.

const sourcemaps = require("gulp-sourcemaps");

gulp.src("src/**/*.js")
  .pipe(sourcemaps.init())
  .pipe(rename({ suffix: ".min" }))
  .pipe(sourcemaps.write())
  .pipe(gulp.dest("dist"));
// Sourcemap file property automatically updated to match renamed file

Path Parsing Details

Directory Handling

The dirname property behavior depends on the glob pattern used in gulp.src():

No globs: dirname is "."
Filename globs (*.txt): dirname is "."
Directory globs (**/, *, [...], {...}): dirname is the path from the directory glob to the file
Base option: When gulp.src() uses base option, dirname is the path from the given base directory to the file

Extension Parsing

By default, extensions are parsed using Node.js Path.extname() behavior:

hello.txt → basename: "hello", extname: ".txt"
hello.min.txt → basename: "hello.min", extname: ".txt"

With multiExt: true option:

hello.min.txt → basename: "hello", extname: ".min.txt"

File Context

When using function parameters, a second file argument provides the complete vinyl file object with properties like path, base, basename, relative, and extname.