Grunt HTML Processor

0.4.4 · abandoned · verified Sun Apr 19

grunt-processhtml is a Grunt plugin designed for modifying HTML files during the build process, adapting their content based on the target release environment. It operates by interpreting special `...` comments within HTML files. These directives allow for operations such as concatenating and replacing script or stylesheet tags with a single optimized file, inlining JavaScript or CSS directly into the HTML, removing specific blocks of content for certain environments, or modifying HTML attributes like `src` or `href`. The current stable version is `0.4.4`, last published 2 years ago, but the latest commit was 8 years ago, and the project is considered effectively abandoned, having seen no significant updates since its last release. Its primary differentiator is its integration with the Grunt task runner and its comment-driven approach to build-time HTML manipulation, but it lacks modern tooling support and is tied to an older ecosystem. While functional for its intended purpose within older Grunt-based workflows, it is not recommended for new projects.

Common errors

```
Warning: Task "processhtml" not found. Use --force to continue.
```
cause The 'grunt-processhtml' plugin was not properly loaded in the `Gruntfile.js`, or the task name was misspelled when attempting to run it.

fix Ensure that `grunt.loadNpmTasks('grunt-processhtml');` is present in your `Gruntfile.js` and that the task is correctly referenced in your `registerTask` calls or command-line arguments (e.g., `grunt processhtml:dist`).
```
Error: Parse error on line X:  Expected build type 'js', 'css', 'remove', 'template', 'include' or attribute like '[href]'. Got 'invalid-type'.
```
cause An unsupported or misspelled 'type' was used within an HTML build comment. The plugin expects specific types or attribute names.

fix Review the `` comment in your HTML file. The `type` must be one of `js`, `css`, `remove`, `template`, `include`, or an HTML attribute enclosed in brackets like `[src]` or `[href]`.
```
Grunt-processhtml remove not working when specifying a target
```
cause Misunderstanding the `build:type[:target]` syntax, specifically how targets interact with the `remove` type. The target in the comment refers to the *Grunt task target* that *should* process the block, not to *remove* it for that specific target by default.

fix For a `remove` block to be removed for a specific target (e.g., `dist`), you typically define it as ``. This means it *will be removed when the `dist` target is active*. If you want it removed for *all but* a specific target, you might need inverse logic or multiple blocks, or configure `customBlockTypes`.

Warnings

breaking The 'grunt-processhtml' package is no longer actively maintained. Its last code commit was over 8 years ago, and the last npm publish was 2 years ago, largely for dependency updates. There will be no further bug fixes, security patches, or feature enhancements.
Fix: Avoid using this package for new projects. For existing projects, consider migrating to more modern HTML processing tools like `gulp-htmlmin`, `html-webpack-plugin`, or standalone NodeJS HTML parsing and transformation libraries.
gotcha The plugin relies heavily on a specific HTML comment syntax () for all its transformations. Deviations from this precise syntax, or conflicts with other HTML comments, can lead to parsing errors, unexpected output, or blocks being ignored.
Fix: Strictly adhere to the documented comment syntax. Thoroughly test and validate the processed HTML output in all build environments to catch any unintended changes or errors. Consider using a linter or schema validator if available.
gotcha This plugin is tightly coupled with the Grunt.js task runner ecosystem. While Grunt remains functional, its usage has declined in favor of more modern build tools like Gulp, Webpack, or Vite. Integrating `grunt-processhtml` requires a full Grunt setup, potentially adding unnecessary complexity to projects not already using Grunt.
Fix: For new projects or those migrating away from Grunt, explore build tools with native HTML processing capabilities or standalone HTML parsers. If using Grunt, ensure your Gruntfile is well-maintained and that all dependencies are up-to-date (though this package itself is not).

Install

npm install grunt-processhtml npm
yarn add grunt-processhtml yarn
pnpm add grunt-processhtml pnpm

Imports

loadNpmTasks
wrong:
```
import { loadNpmTasks } from 'grunt';
```
correct:
```
grunt.loadNpmTasks('grunt-processhtml');
```
Grunt plugins are activated by calling `grunt.loadNpmTasks` in your Gruntfile.js, not through standard JavaScript module import or CommonJS require statements.
processhtml task configuration
wrong:
```
const processhtml = require('grunt-processhtml');
```
correct:
```
grunt.initConfig({ processhtml: { /* ... task target configuration ... */ } });
```
The 'processhtml' task's behavior and file mappings are defined within the `grunt.initConfig` object, under the `processhtml` key. This is a Grunt-specific configuration pattern, not a module import.
processhtml task execution
wrong:
```
processhtml.run();
```
correct:
```
grunt.registerTask('default', ['processhtml:dist']);
```
To run the 'processhtml' task, you invoke it via a Grunt task alias (e.g., 'default') or directly from the command line, referencing its configured targets (e.g., `grunt processhtml:dist`).

Quickstart

Demonstrates `grunt-processhtml` configuration in a `Gruntfile.js` for `dist` and `dev` targets. It shows how to use special HTML comments for concatenating CSS/JS, templating dynamic values (like version and environment), removing development-specific blocks, and modifying attributes based on the build target.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    processhtml: {
      options: {
        data: {
          version: '<%= pkg.version %>',
          env: grunt.option('env') || 'development'
        }
      },
      dist: {
        files: {
          'dist/index.html': ['src/index.html']
        }
      },
      dev: {
        options: {
          data: {
            env: 'development'
          }
        },
        files: {
          'dev/index.html': ['src/index.html']
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-processhtml');

  grunt.registerTask('build', ['processhtml:dist']);
  grunt.registerTask('serve', ['processhtml:dev']);
  grunt.registerTask('default', ['serve']);
};

// src/index.html
<!DOCTYPE html>
<html>
<head>
    <title>My App - <!-- build:template %%= options.env %%= --></title>
    <!-- build:css css/app.min.css -->
    <link rel="stylesheet" href="css/normalize.css">
    <link rel="stylesheet" href="css/main.css">
    <!-- /build -->
</head>
<body>
    <h1>Welcome to Version <!-- build:template %%= options.version %%= --></h1>
    <!-- build:js js/app.min.js -->
    <script src="js/lib.js"></script>
    <script src="js/app.js"></script>
    <!-- /build -->

    <!-- build:remove:dist -->
    <p>This content is for development only.</p>
    <!-- /build -->

    <!-- build:[data-env]:dev -->
    <div data-env="development">Development Environment</div>
    <!-- /build -->
</body>
</html>

view raw JSON →