Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    grunt-excision v1.3.0

    Extract parts from one file into another.

    Getting Started

    This plugin requires Grunt ~0.4.0

    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-contrib-copy --save-dev

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


    This plugin was designed to work with Grunt 0.4.x. 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.3.2.

    Excision task

    Run this task with the grunt excision command.

    Task targets, files and options may be specified according to the grunt Configuring tasks guide.



    Type: Object


    Type: String Values: [js] | css

    Language for validating. JavaScript by default.


    Type: Boolean

    If true, writes destination file despite the validation errors. Useful for debug.


    Type: Object

    This is the hash of source file names and ranges. Range is the instruction how to match and cut the source file. There are several types:

    Type Example Match
    String 'Some text' No match. Just string append
    Array of Strings ['14551', '14585'] Match by decimal offset from start of the file
    Array of Strings ['0x3e28', '0x3e86'] Match by hexademical offset from start of the file
    Array of Numbers [396, 400] Match by line numbers
    RegExp /function slice\([\s\S]*?return[\s\S]*?\}/ Match by regular expression
    String @functionName Match by AST name

    Everything else is nothing more than a syntax sugar. You can construct as much insane as you want: objects inside arrays that contains arrays of objects that contains ranges, etc.

    Usage Examples

    Below is several semi-reallife examples.

    First one is the task for building utils AMD module which includes jquery's trim and lodash's defer functions. Task includes almost every excision's feature just in demonstration purposes, please use it responsibly.

    excision: {
      utils: {
        options: {
          validate: {
            lang: 'js',     // Language for validating (js|css, default: js)
            tolerant: true  // Write dest file despite the errors? (default: false)
          ranges: {
            'bower_components/jquery/dist/jquery.js': {    // Src file path
              trim: { // nop
                '2.1.1': [ // nop
                  'define(function () { var utils = {};',  // Append string
                  'var ', ['14551', '14585'], ';',         // Decimal offset
                  'var ', ['0x3e28', '0x3e86'], ';',       // Hexademical offset
                  'var tmp = {', [396, 400], '};',         // Line numbers range
                  'utils.trim = tmp.trim;'
            'bower_components/lodash/dist/lodash.js': {
              defer: [
                // Regexp match
                /function isFunction\([\s\S]*?return[\s\S]*?\}/,
                /function slice\([\s\S]*?return[\s\S]*?\}/,
                'utils.defer = ', /function defer\([\s\S]*?return.*[\r\n]+.*\}/, ';',
                'return utils; });'
        files: {
          'out/utils.js': [

    Second task builds custom css framework based on bootstrap. Imagine that we don't want whole bootsrap lib on production because it's too complex and large, we need only grid system and tables.

    excision: {
      bootstrap: {
        options: {
          validate: {
            lang: 'css'  // Validate CSS syntax
          ranges: {
            'bower_components/bootstrap/dist/css/bootstrap.css': {  // Src file path
              grid: [1420, 2059],                                   // Line numbers range
              table: [2060, 2293]                                   // Line numbers range
        files: {
          'out/bootstrap.css': 'bower_components/bootstrap/dist/css/bootstrap.css'

    Next one demonstrates the experimental feature, extracting things from JS file by their AST names. Here is the example of extracting isArray function from lodash. Unfortunately now we don't support automatic scope collecting and this needs to be done manually.

    excision: {
      experimental: {
        options: {
          validate: true,
          ranges: {
            'bower_components/lodash/dist/lodash.js': [
              '@isNative',                    // AST name
              'var ', '@objectProto',   ';',  // (internal dependency)
              'var ', '@toString',      ';',  // (internal dependency)
              'var ', '@arrayClass',    ';',  // (internal dependency)
              'var ', '@reNative',      ';',  // (internal dependency)
              'var ', '@nativeIsArray', ';',  // (internal dependency)
              'var ', '@isArray',       ';'   // Yeah, finally got it
        files: {
          'out/experimental.js': 'bower_components/lodash/dist/lodash.js'

    Feel free to contact me through email or issues for any questions.

    Release History

    • 2014-07-23   v1.3.0   Experimental feature: extract things from JS by AST names
    • 2014-07-18   v1.2.0   Add CSSLint for validating CSS
    • 2014-07-17   v1.1.0   Add validate option; Add Esprima for validating JS
    • 2014-07-17   v1.0.2   Refactoring: divide the task and the lib
    • 2014-07-15   v1.0.0   More flexible API; Hex/dec offsets; String appending; Regexp match; Refactoring
    • 2014-07-15   v0.2.0   Add extract bytes option
    • 2014-07-14   v0.1.0   Initial release


    npm i grunt-excision

    Downloadsweekly downloads








    last publish


    • avatar