A document improvement suggestion

I suggest you consider

• adding a VERY EXPLICIT note to the Add Custom Tasks section indicating that the tasks' configuration must be added in application.js, not in the task configuration itself;
• refactoring the example on prependTasks and appendTasks to something like:

prependTasks: {
            common: ["task-1"].concat(app.prependTasks.common)
        },
        appendTasks: {
            common: ["task2"].concat(app.appendTasks.common)
        },

[searls]

Can you point me to the exact wording or send a PR to explain? I'm looking at http://linemanjs.com/#adding-tasks and it seems to explicitly call out config/application.js

[davemo]

Also, if you have suggestions our documentation is open source as well and would love PR's, it's here @dematic-rodrigo-silveira https://github.com/linemanjs/lineman-docs :)

Including a suggestion on how to document the custom tasks section. You will notice that I took a different approach, by including the examples right at the text, which differs from the web-site approach, which has references to the examples; the web-site approach is fine and you could easily do the same the suggestion herein.

Adding Custom Tasks

Introduction

Lineman can easily be extended to do extra grunt-work for your application above-and-beyond the built-in grunt tasks. Lineman provides a folder for you to include custom tasks, tasks. Lineman will automatically require all files in the tasks directory and load them into Grunt.

Below is a very simple custom task sample code for a task that fetches application libraries.

The task

Place this task in the tasks folder.

module.exports = function(grunt) {
    grunt.registerTask('install-libs', ['clean', 'exec']);
};

Note that:

• This task uses the grunt-exec': to install the libraries; see config/application.js for the exec task configuration parameter.
• NOTE: Normally, these tasks' configurations would have been inserted in the object passed to the task's grunt.config.init call
• in lineman case this cannot be done, otherwise the whole lineman's configuration would be overwritten, rendering lineman unable to execute any of its tasks, other then this one!
• see config/application.js below for how to configure the clean and exec tasks.

The task configuration

Use the application.js file, found in the configuration folder, to configure the install-libs task.

module.exports = function(lineman) {
    // DO NOT REMOVE
    var app = lineman.config.application;

    //Override application configuration here. Common examples follow in the comments.
    return {
        // code not included from brevity
        ...

        // Configure the node modules used by your task, grunt-contrib-clean and grunt-exec
        loadNpmTasks: lineman.config.application.loadNpmTasks.concat('grunt-contrib-clean', 'grunt-exec'),

        // Configuration for the grunt-exec module to loade the backbone, bootstrap, and jquery2
        exec: {
            //grunt-exec tasks to load the libraries
            'backbone': 'lineman fetch "backbone"',
            'jquery2': 'lineman fetch "jquery2"'
        },

        // code not included from brevity
        ...
    };
};

Running The Task

From Command Line

Once they're loaded, you can manually run the task from the command line using lineman grunt (which just delegates through to grunt):

$ lineman grunt install-libraries

As Part Of Your Workflow

But you're probably more interested in adding the custom task to run along with the other tasks in lineman run and/or lineman build. You can add any task to these commands by adding it to the appropriate array under the appendTasks object in config/application.js:

module.exports = function(lineman) {
    // DO NOT REMOVE
    var app = lineman.config.application;

    //Override application configuration here. Common examples follow in the comments.
    return {
        // code not included from brevity
        ...

        // Configure where to run the install-libraries task in your workflow
        prependTasks: {
            // Note that the task is being concatenated into the already configured common tasks
            common: app.prependTasks.common.concat(["install-libraries"])

            // This is incorrect and would overwrite the already configured common tasks
            // common:["install-libraries"]
        },

        // code not included from brevity
        ...
    };
};

Additional Workflow Considerations

Lineman has three default workflow tasks:

• common - executed when you execute lineman build and lineman run
• dev - executed when you execute lineman build
• dist - executed when you execute and lineman run

Lineman offers you a mechanism to insert your custom tasks before and after each of its default tasks:

• prependTasks
  • common - execute the configured tasks before the lineman default common tasks is executed
  • dev - execute the configured tasks before the lineman default dev tasks is executed
  • dist - execute the configured tasks before the lineman default dist tasks is executed
• appendTasks
  • common - execute the configured tasks after the lineman default common tasks is executed
  • dev - execute the configured tasks after the lineman default dev tasks is executed
  • dist - execute the configured tasks after the lineman default dist tasks is executed

  prependTasks: {
    common: ["A"],
    dev: ["B"],
    dist: ["C"]
  },
  appendTasks: {
    common: ["D"],
    dev: ["E"],
    dist: ["F"]
  }

In the above example, tasks "A" & "D" would run during both lineman run and lineman build. Meanwhile, "B" & "E" would run only during lineman run, while "C" & "F" would only run during lineman build.

Tasks specified under prependTasks way will be run before Lineman's built-in tasks for the corresponding phase, while tasks specified under appendTasks will run immediately afterward. For reference, check out Lineman's default configuration.

If you need more fine-grained control—say you want to replace or remove a default task—you can use custom JavaScript in your application config file to edit the appropriate array directly; here's an example of removing a task from the Ember.js template.