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.
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
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
List all Gulp tutorials.