Front-Matter Based File Renaming Middleware

1.0.0 verified Thu Apr 23 auth: no javascript maintenance

middleware-rename-file is a Node.js middleware designed for dynamically renaming Vinyl file objects by leveraging properties defined within their YAML front-matter. Currently at version 1.0.0, the package appears to be in a maintenance state, with no active feature development. It targets older Node.js environments (engines >=0.10.0) and is primarily integrated with established templating and static site generation frameworks such as Assemble, Verb, Generate, and Templates. The core functionality allows developers to specify new `basename` and `dirname` attributes directly in a file's front-matter, which the middleware then applies to the file's destination path early in the build pipeline, typically via an `onLoad` event. This declarative approach to file renaming is a key differentiator, providing a structured way to manage file output within its target ecosystems.

Common errors

error TypeError: rename is not a function ↓

cause Attempting to import the CommonJS module using `import` syntax, or trying to access a named export that does not exist.

fix

Use CommonJS require: const renameMiddleware = require('middleware-rename-file');.

error File not renamed as expected ↓

cause The YAML front-matter in the file is missing the `rename` key or its `basename`/`dirname` properties are malformed, or a filter function passed to the middleware is preventing the rename.

fix

Verify the front-matter structure for the rename key and its sub-properties. If a filter function is used, ensure it returns true for files that should be renamed.

Warnings

gotcha This package is designed for CommonJS environments and does not provide native ES module support. Attempting to use `import` syntax will result in errors. ↓

fix Use `const renameMiddleware = require('middleware-rename-file');` for importing the module.

gotcha The package relies on a specific front-matter structure (`rename: { basename: '...', dirname: '...' }`). Incorrectly formatted or missing `rename` properties will prevent files from being renamed as expected. ↓

fix Ensure your file's YAML front-matter includes a top-level `rename` key with `basename` and/or `dirname` properties, for example: ```yaml --- rename: basename: new-name.html dirname: new/path --- ```

deprecated The package specifies Node.js engine compatibility as `>=0.10.0`, indicating it was developed for very old Node.js versions. While its simple functionality might still work, compatibility with modern Node.js versions is not explicitly guaranteed or tested. ↓

fix If encountering issues in modern Node.js environments, consider porting the logic or using a more actively maintained alternative. However, for its specific use-case within the Assemble/Templates ecosystem, it generally remains functional.

gotcha This middleware is specifically designed to integrate with the 'templates' ecosystem (Assemble, Verb, Generate). Its usage outside of these frameworks, particularly with generic Gulp or other build systems, may require manual integration steps for parsing front-matter and handling Vinyl file objects. ↓

fix When using outside of the intended ecosystem, ensure your build process correctly parses front-matter into the `file.data` property and that you are passing valid Vinyl-like file objects to the middleware.

Install

npm install middleware-rename-file

yarn add middleware-rename-file

pnpm add middleware-rename-file

Imports

renameMiddleware

wrong

import renameMiddleware from 'middleware-rename-file';

correct

const renameMiddleware = require('middleware-rename-file');

This package is CommonJS-only. There is no native ESM support.

Quickstart

Demonstrates how to use the `middleware-rename-file` function by mocking a Vinyl file object and applying renaming based on front-matter properties, including an example with a filter function.

const renameMiddleware = require('middleware-rename-file');

// Mock a Vinyl-like file object with front-matter
const fileWithFrontMatter = {
  path: 'scaffolds/layouts/base.hbs',
  contents: Buffer.from('---\nrename:\n  basename: default.hbs\n  dirname: templates\n---\n\n<!DOCTYPE html>...'),
  data: { // `data` property where front-matter is usually parsed
    rename: {
      basename: 'default.hbs',
      dirname: 'templates'
    }
  },
  // Simulate Vinyl file properties
  basename: 'base.hbs',
  dirname: 'scaffolds/layouts',
  extname: '.hbs',
  stem: 'base'
};

const fileWithoutFrontMatter = {
  path: 'src/pages/index.html',
  contents: Buffer.from('<html>...</html>'),
  data: {},
  basename: 'index.html',
  dirname: 'src/pages',
  extname: '.html',
  stem: 'index'
};

const mockApp = {
  emit: (event, file) => {
    // In a real app, this would be `app.emit('file', file)`
    // or similar, passing the transformed file down the pipeline.
    console.log(`
Processed file: ${file.path}`);
    console.log(`  New basename: ${file.basename}`);
    console.log(`  New dirname: ${file.dirname}`);
  }
};

// Initialize the middleware
const rename = renameMiddleware();

// Apply middleware to the first file
rename(fileWithFrontMatter, mockApp);

// Apply middleware to the second file with a filter that prevents renaming 'index' files
const renameWithFilter = renameMiddleware(file => file.stem !== 'index');
renameWithFilter(fileWithoutFrontMatter, mockApp);