vfile utility to rename the path parts of a file


202.0.06 months ago2 years agoMinified + gzip package size for vfile-rename in KB



Build Coverage Downloads Size Sponsors Backers Chat

Rename a vfile.


This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.


npm install vfile-rename


import {toVFile as vfile} from 'to-vfile'
import {rename} from 'vfile-rename'

var file = vfile('readme.md')
file.path // => readme.md

// Set extname:
rename(file, '.html')
file.path // => readme.html

// Set basename:
rename(file, 'main.md')
file.path // => main.md

// Set path properties:
rename(file, {stem: 'index'})
file.path // => index.md

// Change path properties:
rename(file, {stem: {suffix: '.bak'}})
file.path // => index.bak.md

// All together:
rename(file, ['readme.md', '.htm', {stem: 'index', extname: {suffix: 'l'}}])
file.path // => index.html


This package exports the following identifiers: rename, convert. There is no default export.

rename(file, renames)

Renames the given file with renames.

Converts renames to a move, and calls that move with file. If you’re doing a lot of renames, use convert (rename.convert or require('vfile-rename/convert') directly).

  • renames (string, Function, Spec, or Array.<rename>, optional)

The given file.


Create a function (the move) from renames, that when given a file changes its path properties.

  • renames (string, Function, Spec, or Array.<rename>, optional)

A move.


When given something, returns a vfile from that, and changes its path properties.

  • If there is no bound rename (it’s null or undefined), makes sure file is a VFile
  • If the bound rename is a normal string starting with a dot (.), sets file.extname
  • Otherwise, if the bound rename is a normal string, sets file.basename
  • If the bound test is an array, all renames in it are performed
  • Otherwise, if the bound rename is an object, renames according to the Spec


A spec is an object describing path properties to values. For each property in spec, if its value is string, the value of the path property on the given file is set. If the value is object, it can have a prefix or suffix key, the value of the path property on the given file is prefixed and/or suffixed.

Note that only allowed path properties can be set, other properties are thrown for.


See contributing.md in vfile/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.


MIT © Titus Wormer

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.