Broccoli Metal

Easily iterate through and modify all the files in your Broccoli node (tree)

Documentation

Given an input node and a callback function, Broccoli Metal will return a new node based any changes that were performed to the input node within the callback function.

Example Usage

var metal = require('broccoli-metal');
var inputNode = 'src';
module.exports = metal(inputNode, function(files) {
  // `files` is a plain JavaScript object.
  // Each object key is the file name/path and the
  // property values are the string contents of the
  // file.  File paths are relative to the input node.
  //
  // Broccoli Metal will return a new node based on
  // any additions/modifications/deletions performed
  // on the above `files` object.
});

If your project contains the following structure:

├── Brocfile.js
└── src/
    ├── index.js
    ├── css/
    │   ├── reset.css
    │   └── todos.css
    └── javascript/
        ├── app.js
        └── todo.js

then the files object passed to your Broccoli Metal callback function will consist of the following:

metal('src', function(files) {
  console.log(files); //outputs the following:
  /*
  {
    'index.js':           '<string contents of index.js>',
    'css/reset.css':      '<string contents of reset.css>',
    'css/todos.css':      '<string contents of todos.css>',
    'javascript/app.js':  '<string contents of app.js>',
    'javascript/todo.js': '<string contents of todo.js>'
  }
   */
});

The new Broccoli node generated by Broccoli Metal will be based on the modified files object. Deleting an item from the files object results in removing the file from the output node. Adding a new item to the files object results in creating a new file within the output node. And modifying the string contents of an item in the files object will result in modifying the file's contents within the output node.

Given the following project structure (and file contents):

├── Brocfile.js
└── src/
    ├── index.js      // contents = "alert('index.js')"
    ├── css/
    │   ├── reset.css // contents = "body {color: red;}"
    │   └── todos.css // contents = "p {font-size: 12px;}"
    └── javascript/
        ├── app.js    // contents = "alert('app.js')"
        └── todo.js   // contents = "alert('todo.js')"

and when the Brocfile.js contents consists of the following:

var metal = require('broccoli-metal');

module.exports = metal('src', function(files) {
  files['javascript/foo.js'] = "console.log('this is foo.js')";

  delete files['javascript/app.js'];

  delete files['css/todos.css'];
  
  files['css/reset'] = files['css/reset.css'].replace('red', 'blue');

  files['index.js'] = files['index.js'].replace('alert', 'console.log');
});

...then the following new project structure will be created:

└── src/
    ├── index.js      // contents = "console.log('index.js')"
    ├── css/
    │   └── reset.css // contents = "body {color: blue;}"
    └── javascript/
        ├── foo.js    // contents = "console.log('this is foo.js')"
        └── todo.js   // contents = "alert('todo.js')"

In your callback function, you can alternatively return a different object (instead of modifying the provided files object). The new object you return will result in creating a new file structure (relative to the input node).

For example, with the following Brocfile.js:

var metal = require('broccoli-metal');

module.exports = metal('src', function(files) {
  
  return {
    'foo.js': 'alert("this is foo")',
    'css/bar.css': 'body {color: green;}'
  };

});

...Broccoli Metal will return the following Broccoli node:

└── src/
    ├── foo.js      // contents = 'alert("this is foo")'
    └── css/
        └── bar.css // contents = "body {color: green;}"