ZetCode

Gulp rename

last modified November 15, 2026

In this article we rename files in a Gulp 5 pipeline with the gulp-rename plugin. We use its three forms, a string, an object and a function, add .min suffixes, move files into other directories, and look at the case when two files get the same name.

The gulp-rename plugin

Gulp does not rename files by itself. A file in a stream is a Vinyl object with a path, and dest writes it to the place that the path says. The gulp-rename plugin changes the path of the file in the stream. The file on the disk is not touched; the renamed copy is created only when dest writes it. The plugin is used for the .min suffixes of minified files, for moving files into other directories, and for changing extensions.

Installing the project

We create a project and install Gulp and the plugin.

$ mkdir gulp-rename
$ cd gulp-rename
$ npm init -y
$ npm i -D gulp gulp-rename
$ mkdir -p src/js src/css

The example project

The source directory has two scripts, a stylesheet and a text file. The files are tiny because only their names matter.

$ find src -type f | sort
src/css/site.css
src/js/main.js
src/js/util.js
src/notes.txt
$ cat src/js/main.js src/css/site.css src/notes.txt
console.log('main');
body { margin: 0; }
# Notes

The gulpfile

The gulpfile has a task for each form of the plugin. All the paths that rename works with are relative to the base of the glob. For the glob src/**/*.js the base is src, so the path of src/js/main.js is js/main.js.

gulpfile.mjs
import { src, dest } from 'gulp';
import rename from 'gulp-rename';

export function string() {

    return src('src/js/main.js')
        .pipe(rename('app.js'))
        .pipe(dest('dist/string'));
}

export function stringPath() {

    return src('src/js/main.js')
        .pipe(rename('bundle/app.js'))
        .pipe(dest('dist/stringpath'));
}

export function suffix() {

    return src('src/**/*.{js,css}')
        .pipe(rename({ suffix: '.min' }))
        .pipe(dest('dist/suffix'));
}

export function parts() {

    return src('src/notes.txt')
        .pipe(rename({ dirname: 'docs', basename: 'readme', prefix: 'v1-', extname: '.md' }))
        .pipe(dest('dist/parts'));
}

export function mutate() {

    return src('src/**/*.{js,css}')
        .pipe(rename((path) => {
            path.dirname = 'assets/' + path.dirname;
            path.basename += '.' + path.extname.slice(1);
            path.extname = '.txt';
        }))
        .pipe(dest('dist/mutate'));
}

export function returned() {

    return src('src/**/*.{js,css}')
        .pipe(rename((path) => {
            return {
                dirname: path.extname === '.js' ? 'scripts' : 'styles',
                basename: path.basename,
                extname: path.extname
            };
        }))
        .pipe(dest('dist/returned'));
}

export function collision() {

    return src('src/js/*.js')
        .pipe(rename('app.js'))
        .pipe(dest('dist/collision'));
}

We run the tasks one by one and list the files that they create.

A string

The simplest form passes a string, which replaces the whole relative path of the file. The string task renames main.js to app.js.

return src('src/js/main.js')
    .pipe(rename('app.js'))
    .pipe(dest('dist/string'));

The base of src/js/main.js is src/js, and the file lands directly in the output directory.

$ npx gulp string --silent
$ find dist/string -type f
dist/string/app.js

The string can contain directories. The path bundle/app.js puts the file into the bundle subdirectory, which dest creates.

$ npx gulp stringPath --silent
$ find dist/stringpath -type f
dist/stringpath/bundle/app.js

An object

The object form changes only the parts that we name. The suffix property appends text to the base name, before the extension. This is the usual way to create .min files. The glob uses braces to select scripts and stylesheets at once, and the directory structure is kept.

return src('src/**/*.{js,css}')
    .pipe(rename({ suffix: '.min' }))
    .pipe(dest('dist/suffix'));

The three files get the .min suffix in their own directories.

$ npx gulp suffix --silent
$ find dist/suffix -type f | sort
dist/suffix/css/site.min.css
dist/suffix/js/main.min.js
dist/suffix/js/util.min.js

The other properties are prefix, basename, extname and dirname. They can be combined; the parts task changes four parts of notes.txt at once.

rename({ dirname: 'docs', basename: 'readme', prefix: 'v1-', extname: '.md' })

The base name notes was replaced by readme, the prefix was added in front of it, the extension changed, and the file moved to the docs directory.

$ npx gulp parts --silent
$ find dist/parts -type f
dist/parts/docs/v1-readme.md

A function

The function form receives an object with the parts of the path: dirname, basename and extname. We can change it in place, and the plugin uses the changed object. This is useful when the new name depends on the old one.

rename((path) => {
    path.dirname = 'assets/' + path.dirname;
    path.basename += '.' + path.extname.slice(1);
    path.extname = '.txt';
})

Here we move the files into assets, append the old extension to the base name, and give all the files the .txt extension.

$ npx gulp mutate --silent
$ find dist/mutate -type f | sort
dist/mutate/assets/css/site.css.txt
dist/mutate/assets/js/main.js.txt
dist/mutate/assets/js/util.js.txt

The function may also return a new object, or a string with the whole path, instead of changing the argument. The returned task sends scripts and stylesheets to different directories, depending on the extension.

rename((path) => {
    return {
        dirname: path.extname === '.js' ? 'scripts' : 'styles',
        basename: path.basename,
        extname: path.extname
    };
})

Both scripts went to scripts and the stylesheet to styles.

$ npx gulp returned --silent
$ find dist/returned -type f | sort
dist/returned/scripts/main.js
dist/returned/scripts/util.js
dist/returned/styles/site.css

Name collisions

The plugin does not check whether the new name is already used. When several files get the same path, dest writes them one after another, and the last one wins without a warning. The collision task gives the same name to both scripts. Only one file is left, and the content of the other is lost, so a string should be used with a glob only when the glob matches a single file.

return src('src/js/*.js')
    .pipe(rename('app.js'))
    .pipe(dest('dist/collision'));

The output directory has a single file, which holds the text of one of the scripts (in our run, util.js). The order in which the files arrive is not guaranteed, so we cannot tell which one.

$ npx gulp collision --silent
$ find dist/collision -type f
dist/collision/app.js
$ cat dist/collision/app.js
console.log('util');

Source

gulp-rename on npm, Gulp dest

In this article we have renamed files in Gulp 5 with gulp-rename: we used the string, object and function forms, created .min files, moved files into directories, and saw how a name collision loses a file. See also the Gulp Terser and Gulp src and dest tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.