1 | [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
|
2 |
|
3 | # concat (built-in task)
|
4 | Concatenate one or more input files (and/or [directives](helpers_directives.md) output, like `<banner>`) into an output file.
|
5 |
|
6 | ## About
|
7 |
|
8 | This task is a [multi task](types_of_tasks.md), meaning that grunt will automatically iterate over all `concat` targets if a target is not specified.
|
9 |
|
10 | _Need some help getting started with grunt? Visit the [getting started](getting_started.md) page. And if you're creating your own tasks or helpers, be sure to check out the [types of tasks](types_of_tasks.md) page as well as the [API documentation](api.md)._
|
11 |
|
12 | ## A Very Important Note
|
13 | Your `grunt.js` gruntfile **must** contain this code, once and **only** once. If it doesn't, grunt won't work. For the sake of brevity, this "wrapper" code has been omitted from all examples on this page, but it needs to be there.
|
14 |
|
15 | ```javascript
|
16 | module.exports = function(grunt) {
|
17 | // Your grunt code goes in here.
|
18 | };
|
19 | ```
|
20 |
|
21 | ## Project configuration
|
22 |
|
23 | This example shows a brief overview of the [grunt.js gruntfile](getting_started.md) config properties used by the `concat` task. For a more in-depth explanation, see the usage examples.
|
24 |
|
25 | ```javascript
|
26 | // Project configuration.
|
27 | grunt.initConfig({
|
28 | // Project metadata, used by the <banner> directive.
|
29 | meta: {},
|
30 | // Lists of files to be concatenated.
|
31 | concat: {}
|
32 | });
|
33 | ```
|
34 |
|
35 | ## Usage examples
|
36 |
|
37 | ### Concatenating multiple files
|
38 |
|
39 | In this example, running `grunt concat:dist` (or `grunt concat` because `concat` is a [multi task](types_of_tasks.md)) will simply concatenate the three specified source files, in order, writing the output to `dist/built.js`.
|
40 |
|
41 | ```javascript
|
42 | // Project configuration.
|
43 | grunt.initConfig({
|
44 | concat: {
|
45 | dist: {
|
46 | src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
|
47 | dest: 'dist/built.js'
|
48 | }
|
49 | }
|
50 | });
|
51 | ```
|
52 |
|
53 | With a slight modification, running `grunt concat` will join the specified source files using `;` instead of the default newline character.
|
54 |
|
55 | ```javascript
|
56 | // Project configuration.
|
57 | grunt.initConfig({
|
58 | concat: {
|
59 | dist: {
|
60 | src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
|
61 | dest: 'dist/built.js',
|
62 | separator: ';'
|
63 | }
|
64 | }
|
65 | });
|
66 | ```
|
67 |
|
68 | ### Banner comments
|
69 |
|
70 | In this example, running `grunt concat:dist` (or `grunt concat` because `concat` is a [multi task](types_of_tasks.md)) 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`.
|
71 |
|
72 | This generated banner will be the contents of the `meta.banner` underscore 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.
|
73 |
|
74 | _Note: you don't have to use an external JSON file. It's completely 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. See the [directives](helpers_directives.md) page for more information on the `<banner>` and `<json>` directives and their options._
|
75 |
|
76 | ```javascript
|
77 | // Project configuration.
|
78 | grunt.initConfig({
|
79 | pkg: '<json:package.json>',
|
80 | meta: {
|
81 | banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
|
82 | '<%= grunt.template.today("yyyy-mm-dd") %> */'
|
83 | },
|
84 | concat: {
|
85 | dist: {
|
86 | src: ['<banner>', '<file_strip_banner:src/project.js>'],
|
87 | dest: 'dist/built.js'
|
88 | }
|
89 | }
|
90 | });
|
91 | ```
|
92 |
|
93 | ### Multiple build targets
|
94 |
|
95 | 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`.
|
96 |
|
97 | 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](types_of_tasks.md).
|
98 |
|
99 | ```javascript
|
100 | // Project configuration.
|
101 | grunt.initConfig({
|
102 | concat: {
|
103 | basic: {
|
104 | src: ['src/main.js'],
|
105 | dest: 'dist/basic.js'
|
106 | },
|
107 | extras: {
|
108 | src: ['src/main.js', 'src/extras.js'],
|
109 | dest: 'dist/with_extras.js'
|
110 | }
|
111 | }
|
112 | });
|
113 | ```
|
114 |
|
115 | ### Dynamic filenames
|
116 |
|
117 | Filenames can be generated dynamically by using `<%= %>` delimited underscore templates as filenames.
|
118 |
|
119 | 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).
|
120 |
|
121 | ```javascript
|
122 | // Project configuration.
|
123 | grunt.initConfig({
|
124 | pkg: '<json:package.json>',
|
125 | concat: {
|
126 | dist: {
|
127 | src: ['src/main.js'],
|
128 | dest: 'dist/<%= pkg.name %>-<%= pkg.version %>.js'
|
129 | }
|
130 | },
|
131 | });
|
132 | ```
|
133 |
|
134 | ### Advanced dynamic filenames
|
135 |
|
136 | In this more involved example, running `grunt concat` will build two separate files (because `concat` is a [multi task](types_of_tasks.md)). The destination file paths will be expanded dynamically based on the specified underscore templates, recursively if necessary.
|
137 |
|
138 | 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.
|
139 |
|
140 | ```javascript
|
141 | // Project configuration.
|
142 | grunt.initConfig({
|
143 | pkg: '<json:package.json>',
|
144 | dirs: {
|
145 | src: 'src/files',
|
146 | dest: 'dist/<%= pkg.name %>/<%= pkg.version %>'
|
147 | },
|
148 | concat: {
|
149 | basic: {
|
150 | src: ['<%= dirs.src %>/main.js'],
|
151 | dest: '<%= dirs.dest %>/basic.js'
|
152 | },
|
153 | extras: {
|
154 | src: ['<%= dirs.src %>/main.js', '<%= dirs.src %>/extras.js'],
|
155 | dest: '<%= dirs.dest %>/with_extras.js'
|
156 | }
|
157 | }
|
158 | });
|
159 | ```
|
160 |
|
161 | ## Helpers
|
162 |
|
163 | A generic `concat` helper is available for use in any other task where file and/or [directive](helpers_directives.md) concatenation might be useful. In this example, a `;` separator is specified, although it defaults to linefeed if omitted:
|
164 |
|
165 | ```javascript
|
166 | var fooPlusBar = grunt.helper('concat', ['foo.txt', 'bar.txt'], {separator: ';'});
|
167 | ```
|
168 |
|
169 | See the [concat task source](../tasks/concat.js) for more information.
|