broccoli-asset-rewrite

What is broccoli-asset-rewrite?

The broccoli-asset-rewrite npm package is used to rewrite asset URLs in your files. This is particularly useful in build processes where you need to update the paths to assets like images, fonts, and other resources to match the structure of your output directory.

What are broccoli-asset-rewrite's main functionalities?

Basic URL Rewriting

This feature allows you to rewrite URLs in specified file types (e.g., HTML, CSS) by prepending a base URL. This is useful for serving assets from a CDN.

const BroccoliAssetRewrite = require('broccoli-asset-rewrite');

let tree = new BroccoliAssetRewrite(inputTree, {
  replaceExtensions: ['html', 'css'],
  prepend: 'https://cdn.example.com/'
});

Custom Replace Function

This feature allows you to provide a custom replace function to modify URLs in a more flexible way. For example, you can change '/assets/' to '/static/' in your URLs.

const BroccoliAssetRewrite = require('broccoli-asset-rewrite');

let tree = new BroccoliAssetRewrite(inputTree, {
  replaceExtensions: ['html', 'css'],
  replace: function(url) {
    return url.replace('/assets/', '/static/');
  }
});

Exclude Specific Files

This feature allows you to exclude specific files from the URL rewriting process. For example, you can exclude 'index.html' from being processed.

const BroccoliAssetRewrite = require('broccoli-asset-rewrite');

let tree = new BroccoliAssetRewrite(inputTree, {
  replaceExtensions: ['html', 'css'],
  exclude: ['index.html']
});

Other packages similar to broccoli-asset-rewrite

gulp-rev

gulp-rev is a package that allows you to revision static assets by appending content hashes to their filenames. It is similar to broccoli-asset-rewrite in that it helps manage asset URLs, but it focuses more on cache busting through filename changes rather than URL rewriting.

grunt-filerev

grunt-filerev is a Grunt plugin that renames files based on their content hash. Like broccoli-asset-rewrite, it helps manage asset URLs, but it is more focused on cache busting by changing filenames rather than rewriting URLs within files.

webpack

Webpack is a module bundler that can also handle asset management, including URL rewriting and cache busting. It is more comprehensive and complex compared to broccoli-asset-rewrite, offering a wide range of features for modern JavaScript applications.

README

broccoli-asset-rewrite

Broccoli plugin to rewrite a source node from an asset map.

Turns

<script src="assets/appname.js">
background: url('/images/foo.png');

Into

<script src="https://subdomain.cloudfront.net/assets/appname-342b0f87ea609e6d349c7925d86bd597.js">
background: url('https://subdomain.cloudfront.net/images/foo-735d6c098496507e26bb40ecc8c1394d.png');

Installation

npm install broccoli-asset-rewrite --save-dev

Usage

The asset map should have keys of the original names and values of the new names.

var AssetRewrite = require('broccoli-asset-rewrite');

var generatedMap = {
  'assets/appname.css': 'assets/appname-d1d59e0fdcfc183415ab0b72a4f78d9c.css',
  'assets/appname.js': 'assets/appname-ed50537fcd5a71113cf79908f49e854d.js',
  'assets/vendor.css': 'assets/vendor-d41d8cd98f00b204e9800998ecf8427e.css',
  'logo.png': 'logo-c4ab8191636f0a520d1f7f7a82c455a3.png'
};

var assetNode = new AssetRewrite(node, {
  assetMap: generatedMap,
  replaceExtensions: ['html', 'js', 'css'],
  prepend: 'https://subdomain.cloudfront.net/'
});

Options

• assetMap - Default: {} - The asset map to rewrite source from.
• replaceExtensions - Default: ['html', 'css'] - The file types to replace source code with new checksum file names.
• prepend - Default: '' - A string to prepend to all of the assets. Useful for CDN urls like https://subdomain.cloudfront.net/
• ignore - Default: [] - Ignore files from being rewritten.
• annotation - Default: null - A human-readable description for this plugin instance.
• enableCaching - Default: false - Setting to true will enable caching but may cause problems in typical usage with broccoli-asset-rev.

Requirements

Node 10 or higher

Contributors

Originally authored by @rickharrison

Changelog

v3.0.0 (2020-11-30)

:boom: Breaking Change

• #82 Refactor implementation to ES6 class (@lukemelia)
• #77 Specify node 10 support (@lukemelia)

:rocket: Enhancement

• #83 Allow opt-in to caching. (@lukemelia)

:house: Internal

• #84 Add basic linting setup (@rwjblue)
• #80 Add release automation (@rwjblue)
• #78 Migrate to GitHub Actions for CI. (@rwjblue)
• #76 Use broccoli-test-helper to make tests easier to work with (@lukemelia)

Committers: 2

• Luke Melia (@lukemelia)
• Robert Jackson (@rwjblue)