Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Grunt task to replace inline patterns with custom variables.

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

grunt-replace Build Status

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-replace

Then add this line to your project's grunt.js gruntfile:

grunt.loadNpmTasks('grunt-replace');

Overview

Inside your grunt.js file add a section named replace. This section specifies the files to replace.

Parameters

files object

This defines what files this task will copy and should contain key:value pairs.

The key (destination) should be an unique path (supports grunt.template) and the value (source) should be a filepath or an array of filepaths (supports minimatch).

As of v0.3.0, when copying to a directory you must add a trailing slash to the destination due to added support of single file copy.

options object

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

Options

variables object

This option is used to define patterns that will be used to replace the contents of source files.

options: {
  variables: {
    'foo': 'bar'
  }
}
prefix string

This option is used to create the real pattern for lookup in source files (Defaults @@).

basePath string

This option adjusts the folder structure when copied to the destination directory. When not explicitly set, best effort is made to locate the basePath by comparing all source filepaths left to right for a common pattern.

flatten boolean

This option performs a flat copy that dumps all the files into the root of the destination directory, overwriting files if they exist.

minimatch object

These options will be forwarded on to expandFiles, as referenced in the minimatch options section

force boolean

This option force the copy of files even when those files don't have any replace token. Useful when copying a directory.

Config Example

replace: {
  dist: {
    options: {
      variables: {
        'key': 'value'
      },
      prefix: '@@'
    },
    files: {
      'tmp/': ['test/fixtures/dist.txt']
    }
  }
}

Example usage

Variable pattern in source

Define the place where variable will be injected:

// build/manifest.appcache

CACHE MANIFEST
# @@timestamp

CACHE:

favicon.ico
index.html

NETWORK:
*
Gruntfile

Define timestamp variable and destination of the source files:

replace: {
  dist: {
    options: {
      variables: {
        'timestamp': '<%= grunt.template.today() %>'
      }
    },
    files: {
      'public/': ['build/manifest.appcache']
    }
  }
}

Usage variations

Replace over source files (deploy in one target)
replace: {
  dist: {
    options: {
      variables: {
        version: '<%= pkg.version %>',
        timestamp: '<%= grunt.template.today() %>'
      }
    },
    files: {
      'public/': [
        'build/manifest.appcache',
        'build/humans.txt'
      ]
    }
  }
}
Easy cache busting

In app/assets/index.html:

<head>
  <link rel="stylesheet" href="/css/style.css?rel=@@timestamp">
  <script src="/js/app.js?rel=@@timestamp"></script>
</head>

In gruntfile:

replace: {
  dist: {
    options: {
      variables: {
        'timestamp': '<%= new Date().getTime() %>'
      }
    },
    files: {
      'build/index.html': [
        'app/assets/index.html'
      ]
    }
  }
}
Include file contents inplace

In build/index.html:

<body>
  @@include
</body>

In gruntfile:

replace: {
  dist: {
    options: {
      variables: {
        'include': '<%= grunt.file.read("includes/content.html") %>'
      }
    },
    files: {
      'public/': [
        'build/index.html'
      ]
    }
  }
}

Contribute

In lieu of a formal styleguide, take care to maintain the existing coding style.

Release History

  • 2012/09/25 - v0.3.0 - general cleanup and consolidation. test refactoring. global options depreciated. revert normalize linefeeds for now.
  • 2012/09/25 - v0.3.1 - update to grunt-lib-contrib, add force flag.
  • 2012/11/20 - v0.3.2 - add new examples.
Something went wrong with that request. Please try again.