Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gruntjs/grunt-contrib-concat

Concatenate files.
https://github.com/gruntjs/grunt-contrib-concat

hacktoberfest

Last synced: 2 days ago
JSON representation

Concatenate files.

Awesome Lists containing this project

README 

        
# grunt-contrib-concat v2.1.0 [![Build Status](https://github.com/gruntjs/grunt-contrib-concat/workflows/Tests/badge.svg)](https://github.com/gruntjs/grunt-contrib-concat/actions?workflow=Tests)



> Concatenate files.



## Getting Started



If you haven't used [Grunt](https://gruntjs.com/) before, be sure to check out the [Getting Started](https://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](https://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:



```shell

npm install grunt-contrib-concat --save-dev

```



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



```js

grunt.loadNpmTasks('grunt-contrib-concat');

```



## Concat task

_Run this task with the `grunt concat` command._



Task targets, files and options may be specified according to the Grunt [Configuring tasks](http://gruntjs.com/configuring-tasks) guide.



### Options



#### separator

Type: `String`  

Default: `grunt.util.linefeed`



Concatenated files will be joined on this string. If you're post-processing concatenated JavaScript files with a minifier, you may need to use a semicolon `';\n'` as the separator.



#### banner

Type: `String`  

Default: `''`



This string will be prepended to the beginning of the concatenated output. It is processed using [grunt.template.process][], using the default options.



_(Default processing options are explained in the [grunt.template.process][] documentation)_



#### footer

Type: `String`  

Default: `''`



This string will be appended to the end of the concatenated output. It is processed using [grunt.template.process][], using the default options.



_(Default processing options are explained in the [grunt.template.process][] documentation)_



#### stripBanners

Type: `Boolean` `Object`  

Default: `false`



Strip JavaScript banner comments from source files.



* `false` - No comments are stripped.

* `true` - `/* ... */` block comments are stripped, but _NOT_ `/*! ... */` comments.

* `options` object:

  * By default, behaves as if `true` were specified.

  * `block` - If true, _all_ block comments are stripped.

  * `line` - If true, any contiguous _leading_ `//` line comments are stripped.



#### process

Type: `Boolean` `Object` `Function`  

Default: `false`



Process source files before concatenating, either as [templates][] or with a custom function.



* `false` - No processing will occur.

* `true` - Process source files using [grunt.template.process][] defaults.

* `data` object - Process source files using [grunt.template.process][], using the specified options.

* `function(src, filepath)` - Process source files using the given function, called once for each file. The returned value will be used as source code.



_(Default processing options are explained in the [grunt.template.process][] documentation)_



  [templates]: https://github.com/gruntjs/grunt-docs/blob/master/grunt.template.md

  [grunt.template.process]: https://github.com/gruntjs/grunt-docs/blob/master/grunt.template.md#grunttemplateprocess



#### sourceMap

Type: `Boolean`  

Default: `false`



Set to true to create a source map. The source map will be created alongside the destination file, and share the same file name with the `.map` extension appended to it.



#### sourceMapName

Type: `String` `Function`  

Default: `undefined`



To customize the name or location of the generated source map, pass a string to indicate where to write the source map to. If a function is provided, the concat destination is passed as the argument and the return value will be used as the file name.



#### sourceMapStyle

Type: `String`  

Default: `embed`



Determines the type of source map that is generated. The default value, `embed`, places the content of the sources directly into the map. `link` will reference the original sources in the map as links. `inline` will store the entire map as a data URI in the destination file.



### Usage Examples



#### Concatenating with a custom separator



In this example, running `grunt concat:dist` (or `grunt concat` because `concat` is a [multi task][multitask]) will concatenate the three specified source files (in order), joining files with `;` and writing the output to `dist/built.js`.



```js

// Project configuration.

grunt.initConfig({

  concat: {

    options: {

      separator: ';',

    },

    dist: {

      src: ['src/intro.js', 'src/project.js', 'src/outro.js'],

      dest: 'dist/built.js',

    },

  },

});

```



#### Banner comments



In this example, running `grunt concat:dist` will first strip any preexisting banner comment from the `src/project.js` file, then concatenate the result with a newly-generated banner comment, writing the output to `dist/built.js`.



This generated banner will be the contents of the `banner` template string interpolated with the config object. In this case, those properties are the values imported from the `package.json` file (which are available via the `pkg` config property) plus today's date.



_Note: you don't have to use an external JSON file. It's also valid to create the `pkg` object inline in the config. That being said, if you already have a JSON file, you might as well reference it._



```js

// Project configuration.

grunt.initConfig({

  pkg: grunt.file.readJSON('package.json'),

  concat: {

    options: {

      stripBanners: true,

      banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +

        '<%= grunt.template.today("yyyy-mm-dd") %> */',

    },

    dist: {

      src: ['src/project.js'],

      dest: 'dist/built.js',

    },

  },

});

```



#### Multiple targets



In this example, running `grunt concat` will build two separate files. One "basic" version, with the main file essentially just copied to `dist/basic.js`, and another "with_extras" concatenated version written to `dist/with_extras.js`.



While each concat target can be built individually by running `grunt concat:basic` or `grunt concat:extras`, running `grunt concat` will build all concat targets. This is because `concat` is a [multi task][multitask].



```js

// Project configuration.

grunt.initConfig({

  concat: {

    basic: {

      src: ['src/main.js'],

      dest: 'dist/basic.js',

    },

    extras: {

      src: ['src/main.js', 'src/extras.js'],

      dest: 'dist/with_extras.js',

    },

  },

});

```



#### Multiple files per target



Like the previous example, in this example running `grunt concat` will build two separate files. One "basic" version, with the main file essentially just copied to `dist/basic.js`, and another "with_extras" concatenated version written to `dist/with_extras.js`.



This example differs in that both files are built under the same target.



Using the `files` object, you can have list any number of source-destination pairs.



```js

// Project configuration.

grunt.initConfig({

  concat: {

    basic_and_extras: {

      files: {

        'dist/basic.js': ['src/main.js'],

        'dist/with_extras.js': ['src/main.js', 'src/extras.js'],

      },

    },

  },

});

```



#### Dynamic filenames



Filenames can be generated dynamically by using `<%= %>` delimited underscore templates as filenames.



In this example, running `grunt concat:dist` generates a destination file whose name is generated from the `name` and `version` properties of the referenced `package.json` file (via the `pkg` config property).



```js

// Project configuration.

grunt.initConfig({

  pkg: grunt.file.readJSON('package.json'),

  concat: {

    dist: {

      src: ['src/main.js'],

      dest: 'dist/<%= pkg.name %>-<%= pkg.version %>.js',

    },

  },

});

```



#### Advanced dynamic filenames



In this more involved example, running `grunt concat` will build two separate files (because `concat` is a [multi task][multitask]). The destination file paths will be expanded dynamically based on the specified templates, recursively if necessary.



For example, if the `package.json` file contained `{"name": "awesome", "version": "1.0.0"}`, the files `dist/awesome/1.0.0/basic.js` and `dist/awesome/1.0.0/with_extras.js` would be generated.



```js

// Project configuration.

grunt.initConfig({

  pkg: grunt.file.readJSON('package.json'),

  dirs: {

    src: 'src/files',

    dest: 'dist/<%= pkg.name %>/<%= pkg.version %>',

  },

  concat: {

    basic: {

      src: ['<%= dirs.src %>/main.js'],

      dest: '<%= dirs.dest %>/basic.js',

    },

    extras: {

      src: ['<%= dirs.src %>/main.js', '<%= dirs.src %>/extras.js'],

      dest: '<%= dirs.dest %>/with_extras.js',

    },

  },

});

```



#### Invalid or Missing Files Warning

If you would like the `concat` task to warn if a given file is missing or invalid be sure to set `nonull` to `true`:



```js

grunt.initConfig({

  concat: {

    missing: {

      src: ['src/invalid_or_missing_file'],

      dest: 'compiled.js',

      nonull: true,

    },

  },

});

```



See [configuring files for a task](http://gruntjs.com/configuring-tasks#files) for how to configure file globbing in Grunt.



#### Custom process function

If you would like to do any custom processing before concatenating, use a custom process function:



```js

grunt.initConfig({

  concat: {

    dist: {

      options: {

        // Replace all 'use strict' statements in the code with a single one at the top

        banner: "'use strict';\n",

        process: function(src, filepath) {

          return '// Source: ' + filepath + '\n' +

            src.replace(/(^|\n)[ \t]*('use strict'|"use strict");?\s*/g, '$1');

        },

      },

      files: {

        'dist/built.js': ['src/project.js'],

      },

    },

  },

});

```



[multitask]: http://gruntjs.com/creating-tasks#multi-tasks



## Release History



 * 2022-04-03   v2.1.0   Updated dependencies

 * 2021-10-07   v2.0.0   Update dependencies Requires node.js v12+

 * 2016-04-20   v1.0.1   Fix for concatenating multiple source map files.

 * 2016-02-20   v1.0.0   Update source-map to 0.5.3. Tag Grunt as peerDep to >=0.4.0. Make source maps generation a little faster. Add `charset:utf-8` to `sourceMappingURL`.

 * 2015-02-20   v0.5.1   Fix path issues with source maps on Windows.

 * 2014-07-19   v0.5.0   Adds `sourceMap` option.

 * 2014-03-21   v0.4.0   README updates. Output updates.

 * 2013-04-25   v0.3.0   Add option to process files with a custom function.

 * 2013-04-08   v0.2.0   Don't normalize separator to allow user to set LF even on a Windows environment.

 * 2013-02-22   v0.1.3   Support footer option.

 * 2013-02-15   v0.1.2   First official release for Grunt 0.4.0.

 * 2013-01-18   v0.1.2rc6   Updating grunt/gruntplugin dependencies to rc6. Changing in-development grunt/gruntplugin dependency versions from tilde version ranges to specific versions.

 * 2013-01-09   v0.1.2rc5   Updating to work with grunt v0.4.0rc5. Switching back to `this.files` API.

 * 2012-11-13   v0.1.1   Switch to `this.file` API internally.

 * 2012-10-03   v0.1.0   Work in progress, not yet officially released.



---



Task submitted by ["Cowboy" Ben Alman](http://benalman.com/)



*This file was generated on Sun Apr 03 2022 07:55:57.*