Taming a Legacy Gruntfile: Multitasks, Options Merging, and Templates That Actually Stay Readable

If you've inherited a project whose build still runs on Grunt, you've probably opened the Gruntfile once, seen 400 lines of near-duplicate configuration, and quietly closed it again. The good news: most of that duplication is optional. Grunt has three features — multitask targets, hierarchical options merging, and template strings — that exist specifically to keep build config DRY. Used together, they can shrink a sprawling Gruntfile into something you can actually reason about.

This post walks through those features with a concrete example, then covers the one merging behavior that bites people in production.

One plugin, many build profiles: multitask targets

Almost every grunt-contrib-* plugin is a multitask: a single task name that accepts multiple named targets. Instead of registering uglifyDev and uglifyProd as separate things, you define two targets under one task:

grunt.initConfig({
  uglify: {
    dev: {
      options: { mangle: false, sourceMap: true },
      files: { 'dist/app.js': ['src/**/*.js'] }
    },
    dist: {
      options: { mangle: true, compress: true },
      files: { 'dist/app.min.js': ['src/**/*.js'] }
    }
  }
});
grunt.loadNpmTasks('grunt-contrib-uglify');

Running grunt uglify:dev executes just the dev target; grunt uglify runs all targets in order. This is the canonical pattern for build profiles: one plugin, one config block, several outputs. The same structure applies to concat, watch, copy, and nearly everything else in the contrib family.

Defaults plus overrides: how options merging works

Options merge hierarchically. Options set at the task level apply to every target; options set at the target level override them for that target only. That gives you a clean "defaults plus exceptions" style:

uglify: {
  options: {
    banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */',
    mangle: true
  },
  dev: {
    options: { mangle: false, sourceMap: true },
    files: { 'dist/app.js': ['src/**/*.js'] }
  },
  dist: {
    files: { 'dist/app.min.js': ['src/**/*.js'] }
  }
}

Here dist inherits the banner and mangling from the task level and adds nothing of its own, while dev opts out of mangling and adds a source map. When you add a third target later, it starts from the shared defaults instead of a copy-paste of an existing block.

Templates and globbing: stop hardcoding paths

Grunt evaluates <%= %> template strings against your config object, and a common first line of any Gruntfile is pkg: grunt.file.readJSON('package.json'). From then on, <%= pkg.name %>, <%= pkg.version %>, and any custom config paths you define are available everywhere — banners, output filenames, destination directories. Edit package.json and the build output follows without touching the Gruntfile.

The second half of the story is the file object. The expand/cwd/src/dest form handles many-to-many mappings, which is where most real asset pipelines live:

copy: {
  assets: {
    expand: true,
    cwd: 'src/assets/',
    src: ['**/*.{png,svg,css}'],
    dest: 'dist/assets/'
  }
}

expand: true tells Grunt to build a per-file mapping instead of treating src as one concatenated input; cwd keeps the destination paths relative to the source root rather than mirroring the full directory tree. If a glob isn't matching what you expect, run grunt copy --verbose — verbose mode prints the expanded file list, which is the fastest way to debug patterns.

Tie it together with an alias task and watch:

grunt.registerTask('default', ['copy', 'uglify:dist']);

One command runs the ordered pipeline; grunt-contrib-watch targets can re-run individual steps (e.g. only uglify:dev) when matching files change.

The trade-off: arrays replace, they don't merge

Here's the limitation worth memorizing. Grunt's options merging is deep for plain objects, but arrays are replaced, not concatenated. If your task-level options include an array — say a list of files to exclude, or plugin-specific flags — and a target sets its own array for the same key, the task-level array is gone. Not merged, not appended: replaced. This has silently dropped exclusions in real builds and produced minified bundles containing files that should never have shipped.

The practical defenses:

• Keep arrays at the target level only, unless every target genuinely wants the identical list.
• If a target needs "defaults plus one more," spell out the full array in the target. It's slightly less DRY but explicit and safe.
• When in doubt about what a target actually resolved to, run grunt <task>:<target> --verbose and read the effective config in the output rather than guessing from the Gruntfile.

Also note that exact merge behavior can vary across plugin major versions, so check the README of the plugin version you actually have installed before relying on subtle merging semantics.

A word on context, and what to do next

Grunt is maintenance-territory software: stable, working, but largely superseded by npm scripts, webpack, and esbuild for new projects. The point of learning its config model isn't to adopt it fresh — it's to make the builds you already have legible enough to maintain, and eventually to migrate with confidence because you understand what the Gruntfile actually does.

Concretely: pick your most duplicated task this week, collapse it into multitask targets with task-level defaults, move hardcoded names into <%= pkg.* %> templates, and audit every array-valued option for the replacement trap. Then verify with --verbose that the expanded file lists and effective options match what you intended. That's an afternoon of work for a Gruntfile the next maintainer won't be afraid of.