Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An awesome little utility for no fuss source file includes through grunt, compatible with all file types in your arsenal.
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


An awesome little utility for no fuss source file includes through grunt, compatible with all file types in your arsenal.

Getting Started

This plugin requires Grunt ~0.4.1

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-dead-simple-include --save-dev

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


The "dead_simple_include" task


In your project's Gruntfile, add a section named dead_simple_include to the data object passed into grunt.initConfig().

  dead_simple_include: {
    options: {
      // Task-specific options go here.
    your_target: {
      // Target-specific file lists and/or options go here.



Type: Array Default value: ['js', 'coffee']

An array of file extensions that should be included in the result set.


Type: Boolean Default value: true

A flag to signal whether nor the task should include files that are not explicitly included through files. With this flag set to false, only files referenced in an file will be part of the output.


Type: String Default value: //

You can include comments in files, comments are denoted by the given commentString which can be any string value except for the directives 'include' and 'skip'


Type: String Default value: ''

When the task finishes you may optionally add a string that will prefix the resulting paths. An example use might be ../ or src/


Type Object Default value: {}

When the task finishes running you may optionally define a wrapping string for each file extension type given. Example:

options: {
    wrapper: {
        js: ['<script type="text/javascript" src="', '"></script>'],
        css: ['<link rel=stylesheet href="', '">']

The output result would then be: <script type="text/javascript" src="path/to/your/file.js"></script> instead of path/to/your/file.js

If no wrapper is defined for an extension, it will not be wrapped. Wrapping is defined by a two element array where wrapper[extension][0] is the start of the wrap and wrapper[extension][1] is the end.


Type String Default value: null

This is the file path to the location of your source tree. If a value is not supplied the task will not run.


Type String Default value: `tmp/includes.txt'

This is the output destination of the task.

Usage Examples

This task will traverse your source tree in directory-then-file-alphabetical order and write the encountered file paths to an output file that you can then feed other grunt tasks to process further. You can alter the order of inclusion or explicitly skip a file or directory by adding files to your source tree.

The format of these files is simple, on each line you can add one of two directives: include or skip along with a relative file path. Here is an example

//this is a comment!

include utils
include app.js
include models/user.js
skip style.css

Given this file structure

  • src
    • models
      • user.js
    • utils
      • math.js
      • random.js
    • app.js
    • style.css

The output of this task would be


If we were to add the above to the src directory, the output would be


Note that files are not included in the output.

Paths within an file are relative, but you are allowed to backtrack via ../. Assuming these files exist in some structure, these are both valid paths in an include file:

include ../user/phone_number.js
include my_file.js

You may not explicitly include an include file, the targets of an include may be a directory, in which case the directory is checked for an file. If one exists, includes proceed as defined in that file. Otherwise the directory is traversed normally, in directory-then-file-alphabetical order.


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.

Something went wrong with that request. Please try again.