@firstfleet/replacer-brunch

Ruthlessly simple string replacement plugin to Brunch.

This is a fork of (replacer-brunch)[https://github.com/firstfleetinc/replacer-brunch]. There have been some modifications, they are as follows.

ESM Support ONLY version 2.0.0 and >

This how now been converted to an ES module. In order to use this with brunch, you have to modify brunch itself to use common js dynamic imports. Firstfleet uses a custom patch to allow ESM support in brunch.

Public url rewriting for .html files

This fork also supports key rewriting in .html files from the assets directory. This is so when you build your front-end application for production, you can overwrite the base url in the index.html file if your app does not live at the root of the domain. See the public url rewrite section below.

Global replace

By default, the replace method will now replace the defined key in the entire file, rather than just replacing the first instance. This was achieved by replacing the default replace definition of

    if (!this.config.replace) {
      this.config.replace = (str, key, value) => str.replace(key, value);
    }

With

    // Set default replace method
    if (!this.config.replace) {
      this.config.replace = (str, key, value) => {
        const reg = new RegExp(key, "g");

        return str.replace(reg, value);
      };
    }

Pattern Overrirde

You can now change the file patterns this plugin will process, and the default file pattern has been updated. The previous file pattern was

BrunchReplacer.prototype.pattern = /\.jsx?$/;

and has been updated to

BrunchReplacer.prototype.pattern = /\.(js|svelte|jsx)?$/;

You can also overwrite the pattern in the configuration.

replacer: {
        pattern: /\.jsx?$/, // Here you can specify the the pattern
        dict: [
            // Replace pubnub pub key in js files
            {
                key: "__PUBLICURL__",
            },
            {
                key: "__SUBROUTE__",
            },
        ],
    },

Configuration

replacer: {
  // dict is an array containing objects with key and value property.
  // String replacements are processed in order from first to last.
  dict: [
    {
      // key will be replaced by value.
      key: '__KEY__',
      value: '__VALUE__'
    },
    {
      // You can use anything as value.
      // Non-string values will be passed through JSON.stringify().
      key: '__PACKAGE__',
      value: require('./package.json')
    },
    {
      // By default replacer uses String.replace(), so only the first
      // occurrence will be replaced if you use a string as key.
      // You can use a global regex to replace all occurrences.
      key: /__ENV__/g,
      value: process.env.NODE_ENV
    },
    {
      // Use cases: getting NODE_ENV, package.json values,
      // custom configuration JSON, generate random string, etc.
      key: /{#VERSION}/g,
      value: 'v1.0.0'
    },
    {
      key: 'remove_me'
      // If value is omitted, the replacement is the empty string
    }
  ],
  // By default replacer uses String.replace() function.
  // If you want to use a different function, you can supply
  // your own replacement function here with this signature:
  //  - str (string) - string to be processed
  //  - key (any) - key from the dict
  //  - value (string) - replacement value
  //  - path (string) - the path of the file being processed
  replace: (str, key, value, path) => str.split(key).join(value)
}

For example, to replace __filename with the name of the file being processed, you can use:

replacer: {
  dict: [
    {
      key: /\b__filename\b/,
      // No value needed - the custom replacer below supplies it
    }
  ],
  replace: (str, key, value, path) => {
    return str.split(key).join(`'${path}'`);
  }
}

Public URL Rewrite for index.html

This is needed if you want to be able to run your dev server locally with brunch watch --server, and you also need to be able to ship your app to a domain that is not the root directory of the website. So, say your app will be deployed to https://mywebsite.com/apps/appname. Currently, if you brunch build --production and copy and paste your files over to the server, without making changes to the server your app won't be able to fetch your files. This is cause your files don't live at / which you need them to be when running your dev server, they live at https://mywebsite.com/apps/appname. To rewrite your public url for production, add this to your brunch config under module.exports.plugins.

// replace keys in js files with values in the .env file
    replacer: {
        dict: [
            // Replace pubnub pub key in js files
            {
                key: "__PUBLICURL__",
            },
        ],
    },

This will remove the __PUBLICURL__ when running brunch watch --server

Then, add an override for production build.

module.exports.overrides = {
    production: {
        plugins: {
            // replace keys in js files with values in the .env file
            replacer: {
                dict: [
                    // Replace pubnub pub key in js files
                    {
                        key: "__PUBLICURL__",
                        value: "https://firstfleetinc.com/apps/ffadmindashboard",
                    },
                ],
            },
        },
    },
};

This will overwrite your key __PUBLICURL__ when you bulid for production brunch build --production.

Lastly, add your key __PUBLICURL__ to your index.html file under the assets folder.

<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
	<meta charset='utf-8'>
	<meta name='viewport' content='width=device-width,initial-scale=1'>

	<title>Admin Dashboard</title>

    <link rel='icon' type='image/png' href='__PUBLICURL__/icons/favicon.png'>
    <link rel="stylesheet" href="__PUBLICURL__/app.css" />
    <script defer src="__PUBLICURL__/app.js"></script>
</head>

<body>
</body>
</html>

Now, when you run your development server, everything will work just as before, and when you build for production, your public url will be correctly prefexed to your index.html file.

Installation

Install the plugin via npm with npm install --save-dev @firstfleet/replacer-brunch.

License

Licensed under MIT License.

Contributors

• Ted Kesgar
• Chris White
• Jess Patton