{"id":17804,"library":"middleware-rename-file","title":"Front-Matter Based File Renaming Middleware","description":"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.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jonschlinkert/middleware-rename-file","tags":["javascript","assemble","file","front-matter","generate","middleware","rename","rewrite","template"],"install":[{"cmd":"npm install middleware-rename-file","lang":"bash","label":"npm"},{"cmd":"yarn add middleware-rename-file","lang":"bash","label":"yarn"},{"cmd":"pnpm add middleware-rename-file","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only. There is no native ESM support.","wrong":"import renameMiddleware from 'middleware-rename-file';","symbol":"renameMiddleware","correct":"const renameMiddleware = require('middleware-rename-file');"}],"quickstart":{"code":"const renameMiddleware = require('middleware-rename-file');\n\n// Mock a Vinyl-like file object with front-matter\nconst fileWithFrontMatter = {\n path: 'scaffolds/layouts/base.hbs',\n contents: Buffer.from('---\\nrename:\\n basename: default.hbs\\n dirname: templates\\n---\\n\\n...'),\n data: { // `data` property where front-matter is usually parsed\n rename: {\n basename: 'default.hbs',\n dirname: 'templates'\n }\n },\n // Simulate Vinyl file properties\n basename: 'base.hbs',\n dirname: 'scaffolds/layouts',\n extname: '.hbs',\n stem: 'base'\n};\n\nconst fileWithoutFrontMatter = {\n path: 'src/pages/index.html',\n contents: Buffer.from('...'),\n data: {},\n basename: 'index.html',\n dirname: 'src/pages',\n extname: '.html',\n stem: 'index'\n};\n\nconst mockApp = {\n emit: (event, file) => {\n // In a real app, this would be `app.emit('file', file)`\n // or similar, passing the transformed file down the pipeline.\n console.log(`\nProcessed file: ${file.path}`);\n console.log(` New basename: ${file.basename}`);\n console.log(` New dirname: ${file.dirname}`);\n }\n};\n\n// Initialize the middleware\nconst rename = renameMiddleware();\n\n// Apply middleware to the first file\nrename(fileWithFrontMatter, mockApp);\n\n// Apply middleware to the second file with a filter that prevents renaming 'index' files\nconst renameWithFilter = renameMiddleware(file => file.stem !== 'index');\nrenameWithFilter(fileWithoutFrontMatter, mockApp);\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Use `const renameMiddleware = require('middleware-rename-file');` for importing the module.","message":"This package is designed for CommonJS environments and does not provide native ES module support. Attempting to use `import` syntax will result in errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your file's YAML front-matter includes a top-level `rename` key with `basename` and/or `dirname` properties, for example:\n```yaml\n---\nrename:\n basename: new-name.html\n dirname: new/path\n---\n```","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Use CommonJS `require`: `const renameMiddleware = require('middleware-rename-file');`.","cause":"Attempting to import the CommonJS module using `import` syntax, or trying to access a named export that does not exist.","error":"TypeError: rename is not a function"},{"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.","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.","error":"File not renamed as expected"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}