Home

Awesome

grunt-string-replace Build Status

Replaces strings on files by using string or regex patterns. Attempts to be a String.prototype.replace adapter task for your grunt project.

Getting Started

This plugin requires node >= 0.10.0, Grunt >= 0.4.0 and npm >= 1.4.15 (latest stable is recommended).

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-string-replace --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks("grunt-string-replace");

If you're still using grunt v0.3.x it's strongly recommended that you upgrade, but in case you can't please use v0.1.1-1.

Configuration

Inside your Gruntfile.js file add a section named string-replace. This section specifies the files to edit, destinations, patterns and replacements.

Parameters

files object

Defines what files this task will edit. Grunt itself has very powerful abstractions, so it is highly recommended you understand the different ways to specify them. Learn more at Gruntfile Files mapping, some options incude compact format, files object format and files array format.

options object

Controls how this task operates and should contain key:value pairs, see options below.

options.saveUnchanged boolean

By default true this flag will instruct grunt-string-replace to copy the files on options.replacements patterns even if there are no replacing matches.

By setting this flag to false files that have not changed (no replacements done) will not be saved on the new location. This will speed up the task if there is a large number of files.

options.replacements array

This option will hold all your pattern/replacement pairs. A pattern/replacement pair should contain key:value pairs containing:

options: {
  replacements: [
    {
      pattern: /\/(asdf|qwer)\//gi,
      replacement: '"$1"',
    },
    {
      pattern: ",",
      replacement: ";",
    },
  ];
}

Notes

Examples

Multiple files and multiple replacements

'string-replace': {
  dist: {
    files: {
      'dest/': 'src/**',
      'prod/': ['src/*.js', 'src/*.css'],
    },
    options: {
      replacements: [{
        pattern: /\/(asdf|qwer)\//ig,
        replacement: ''$1''
      }, {
        pattern: ',',
        replacement: ';'
      }]
    }
  }
}

Simple inline content

'string-replace': {
  inline: {
    files: {
      'dest/': 'src/**',
    },
    options: {
      replacements: [
        // place files inline example
        {
          pattern: '<script src='js/async.min.js'></script>',
          replacement: '<script><%= grunt.file.read('path/to/source/js/async.min.js') %></script>'
        }
      ]
    }
  }
}

Using files' expand options

For more details, see Grunt's documentation about dynamic files object.

'string-replace': {
  dist: {
    files: [{
      expand: true,
      cwd: 'src/',
      src: '**/*',
      dest: 'dist/'
    }],
    options: {
      replacements: [{
        pattern: 'hello',
        replacement: 'howdy'
      }]
    }
  }
}

Advanced inline

Since grunt-string-replace is basically a wrapper of String.prototype.replace you can also provide a function as a replacement pattern instead of a string or a template; as a nice added bonus to using a replacement function, grunt-string-replace will provide 2 extra arguments apart from the ones documented in the link below: src and dest. To get more details about how to use a function as replacement pattern I recommend you to read Specifying a function as a parameter.

We will be reading file names from HTML comments and use the paths later to fetch the content and insert it inside a resulting HTML. Assuming the following setup:

src/index.html

<!-- @import partials/header.html -->
content here
<!-- @import partials/footer.html -->

src/partials/header.html

<html>
  <head></head>
  <body></body>
</html>

src/partials/footer.html

</body></html>

Gruntfile.js

'use strict';

module.exports = function (grunt) {
  // Project configuration.
  grunt.initConfig({
    config: {
      src: 'src/*.html'
      dist: 'dist/'
    },
    'string-replace': {
      dist: {
        files: {
          '<%= config.dist %>': '<%= config.src %>'
        },
        options: {
          replacements: [{
            pattern: /<!-- @import (.*?) -->/ig,
            replacement: function (match, p1) {
              return grunt.file.read(grunt.config.get('config.dist') + p1);
            }
          }]
        }
      }
    }
  });

  // These plugins provide necessary tasks.
  grunt.loadNpmTasks('grunt-string-replace');

  // Default task.
  grunt.registerTask('default', ['string-replace']);
};

After executing grunt we get the following:

dist/index.html

<html>
  <head></head>
  <body>
    content here
  </body>
</html>

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Release History

1.3.3

1.3.2

1.3.1

1.3.0

1.2.1

1.2.0

1.1.1

1.1.0

1.0.0

0.2.8

0.2.7

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.1-1

0.1.1

0.1.0-1

0.1.0

License

Copyright (c) 2016 Erick Ruiz de Chavez. Licensed under the MIT license.