build-workflow

7.0.1 verified Sat Apr 25 auth: no javascript maintenance

A Gruntfile helper that breaks monolithic Gruntfiles into manageable modules. Current stable version is 7.0.1, with maintenance-level updates as needed. It organizes configs, custom tasks, and workflow aliases into separate files under 'grunt-deps/' and automatically loads them. Unlike alternatives like load-grunt-configs, it uses plain JavaScript (not YAML) for aliases and passes grunt/pkg objects to config functions. Primarily useful for legacy Grunt projects; the author recommends npm scripts for new projects.

Common errors

error Warning: Task "<task>" not found. Use --force to continue. ↓

cause The task name in aliases or command line doesn't match any loaded task.

fix

Ensure the task file exists in grunt-deps/tasks or that the task is registered via grunt.registerTask.

error TypeError: grunt.task.registerTask is not a function ↓

cause Aliases.js exports an object instead of a function that receives grunt.

fix

Change module.exports = {...} to module.exports = function(grunt) { grunt.registerTask(...); };

error Cannot find module 'grunt' ↓

cause Grunt is not installed as a dev dependency.

fix

Run: npm install --save-dev grunt

error Fatal error: Unable to find Gruntfile.js ↓

cause Current directory doesn't contain a Gruntfile.js.

fix

Create a Gruntfile.js in the project root (see quickstart).

Warnings

deprecated Package author recommends using npm scripts instead of Grunt for new projects. ↓

fix For new projects, use npm scripts (scripts in package.json) or a modern build tool like webpack/vite.

gotcha Config files must export a function that returns an object, not just an object. Otherwise configs won't load. ↓

fix Ensure every file in grunt-deps/configs exports a function: module.exports = function(grunt) { return { ... }; };

gotcha Aliases file must be in grunt-deps/workflows/aliases.js and export a function that registers tasks. ↓

fix Create the file with module.exports = function(grunt) { grunt.registerTask('default', [...]); };

gotcha Custom tasks in grunt-deps/tasks are automatically loaded, but their filenames must match the task name. ↓

fix Name your files exactly as the task (e.g., hello.js for task 'hello').

Install

npm install build-workflow

yarn add build-workflow

pnpm add build-workflow

Imports

buildWorkflow

wrong

import buildWorkflow from 'build-workflow';

correct

const buildWorkflow = require('build-workflow');

This package is CJS-only and does not provide ESM exports.

default
wrong
```
import buildWorkflow from 'build-workflow';
buildWorkflow(grunt);
```
correct
```
require('build-workflow')(grunt);
```
The module exports a single function. Invoke it immediately with the grunt instance.

aliases

wrong

module.exports = { 'default': ['task1'] };

correct

// In grunt-deps/workflows/aliases.js:
module.exports = function(grunt) { grunt.registerTask('default', ['task1']); };

Alias files must export a function that registers tasks; plain objects are not supported.

Quickstart

Shows minimal setup: folder structure, Gruntfile, alias, custom task, and execution with grunt.

mkdir -p grunt-deps/configs grunt-deps/tasks grunt-deps/workflows
cat > Gruntfile.js << 'EOF'
module.exports = function(grunt) {
  'use strict';
  require('build-workflow')(grunt);
};
EOF
cat > grunt-deps/workflows/aliases.js << 'EOF'
module.exports = function(grunt) {
  grunt.registerTask('default', ['hello']);
};
EOF
cat > grunt-deps/tasks/hello.js << 'EOF'
module.exports = function(grunt) {
  grunt.registerTask('hello', function() {
    grunt.log.writeln('Hello from build-workflow!');
  });
};
EOF
npm init -y && npm install --save-dev grunt build-workflow
grunt