tessl/npm-grunt-preprocess

Grunt plugin for preprocessing HTML and JavaScript files with environment-based directives

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

grunt-preprocess

Name: tessl/npm-grunt-preprocess
Author: tessl

grunt-preprocess is a Grunt plugin that provides preprocessing capabilities for HTML and JavaScript files using environment-based directives. It wraps the 'preprocess' npm module to enable conditional compilation and template-like functionality in web development workflows.

Package Information

Package Name: grunt-preprocess
Package Type: npm (Grunt plugin)
Language: JavaScript
Installation: npm install --save-dev grunt-preprocess

Core Imports

Load the task in your Gruntfile:

grunt.loadNpmTasks('grunt-preprocess');

For programmatic usage (initialize with Grunt instance):

const gruntPreprocess = require('grunt-preprocess');
// Initialize the task with a Grunt instance
gruntPreprocess(grunt);

CommonJS import:

const gruntPreprocess = require('grunt-preprocess');

CLI usage:

grunt-preprocess

Basic Usage

Configure the preprocess task in your Gruntfile:

module.exports = function(grunt) {
  grunt.initConfig({
    preprocess: {
      options: {
        context: {
          NODE_ENV: 'production',
          DEBUG: false
        }
      },
      html: {
        src: 'src/index.html',
        dest: 'dist/index.html'
      },
      js: {
        src: 'src/app.js',
        dest: 'dist/app.js'
      }
    }
  });

  grunt.loadNpmTasks('grunt-preprocess');
  grunt.registerTask('build', ['preprocess']);
};

Input file with preprocessor directives:

<head>
  <title>My App</title>
  
  <!-- @if NODE_ENV='production' -->
  <script src="analytics.js"></script>
  <!-- @endif -->
  
  <!-- @ifdef DEBUG -->
  <script src="debug-tools.js"></script>
  <!-- @endif -->
</head>
<body>
  <h1><!-- @echo RELEASE_TAG --></h1>
  <p>
  <!-- @include welcome_message.txt -->
  </p>
</body>

Capabilities

Module Structure

The package exports a single initialization function as the main module:

/**
 * Main module export - initialization function
 * @param grunt - Grunt instance to register task with
 * @returns void - Registers 'preprocess' multi-task with Grunt
 */
declare function gruntPreprocess(grunt: GruntInstance): void;

// Default export
export = gruntPreprocess;

// Module structure
interface ModuleExports {
  /** Main export is the init function */
  default: typeof gruntPreprocess;
  /** No named exports - single function export */
}

Grunt Task Registration

The main entry point that registers the 'preprocess' multi-task with Grunt.

/**
 * Initialize and register the preprocess task with Grunt
 * @param grunt - Grunt instance with registerMultiTask method
 */
function init(grunt: GruntInstance): void;

Preprocess Task Configuration

The preprocess task accepts the following configuration options through standard Grunt task configuration:

interface PreprocessTaskConfig {
  /** Task-specific options */
  options?: PreprocessOptions;
  /** File configuration */
  src?: string;
  dest?: string;
  files?: { [dest: string]: string } | FileConfig[];
}

interface PreprocessOptions {
  /** Additional context variables for template processing */
  context?: { [key: string]: any };
  /** Enable overwriting source files in-place */
  inline?: boolean;
  /** Directory to look for @include files and @extend directives */
  srcDir?: string;
  /** End-of-line character for preprocessed output */
  srcEol?: string;
  /** Syntax type for preprocessing */
  type?: string;
}

interface FileConfig {
  src: string[];
  dest?: string;
  expand?: boolean;
  cwd?: string;
  ext?: string;
}

Context Processing

Environment and custom variables are merged for template processing:

/**
 * Context merging follows this precedence (highest to lowest):
 * 1. Task-level context options
 * 2. Global task context options  
 * 3. process.env environment variables
 * 
 * NODE_ENV defaults to 'development' if not set
 */
interface ContextMerging {
  context: {
    NODE_ENV: string; // Defaults to 'development'
    [key: string]: any; // Custom variables
  };
}

File Processing Modes

Single File Processing

Process a single source file to a destination:

preprocess: {
  html: {
    src: 'src/index.html',
    dest: 'dist/index.html'
  }
}

Multi-file Object Processing

Process multiple files using a files object:

preprocess: {
  multifile: {
    files: {
      'dist/app.js': 'src/app.js',
      'dist/styles.css': 'src/styles.css'
    }
  }
}

Expanded Files Processing

Process files using glob patterns with expanded configuration:

preprocess: {
  all_templates: {
    src: '**/*.tmpl',
    ext: '.html',
    cwd: 'src',
    dest: 'build',
    expand: true
  }
}

Inline Processing

Overwrite source files in-place (requires inline: true option):

preprocess: {
  inline: {
    src: ['src/**/*.js'],
    options: {
      inline: true,
      context: {
        MINIFIED: true
      }
    }
  }
}

Configuration Options

context

Type: Object
Default: {NODE_ENV: 'development'}

Additional context variables for template processing beyond environment variables:

options: {
  context: {
    VERSION: '1.2.0',
    API_URL: 'https://api.example.com',
    DEBUG: true,
    customFunction: function(param) {
      return param + '-processed';
    }
  }
}

inline

Type: Boolean
Default: undefined

Required flag to enable overwriting source files. Must be explicitly set to true for safety:

options: {
  inline: true // Required for in-place file modification
}

srcDir

Type: String
Default: Directory path of source file

Directory where @include and @extend directives should look for files:

options: {
  srcDir: 'templates/'  // Look for includes in templates/ directory
}

srcEol

Type: String
Default: Source file EOL or os.EOL

End-of-line character for preprocessed output:

options: {
  srcEol: '\n'     // Unix line endings
  // srcEol: '\r\n' // Windows line endings  
  // srcEol: '\r'   // Legacy Mac line endings
}

type

Type: String
Default: File extension of source file

Override the syntax type for preprocessing when it can't be determined from file extension:

options: {
  type: 'html'  // Force HTML preprocessing for .tmpl files
}

Additional Options

Additional options are passed through to the underlying 'preprocess' module:

options: {
  fileNotFoundSilentFail: true  // Silently ignore missing @include files
}

Command Line Interface

Binary executable for running grunt-preprocess from the command line:

# Global installation and usage
npm install -g grunt-preprocess
grunt-preprocess

# NPX usage (recommended)
npx grunt-preprocess

# Direct binary usage after local install
./node_modules/.bin/grunt-preprocess

The CLI binary (bin/grunt-preprocess) is a simple wrapper that delegates to Grunt's CLI system:

/**
 * CLI binary that loads and executes grunt-preprocess tasks
 * Delegates to grunt.npmTasks('grunt-preprocess').cli()
 */
interface CLIBinary {
  /** Executable path from package.json bin field */
  executable: "bin/grunt-preprocess";  
  /** Requires Grunt to be available in the project */
  requirement: "grunt";
}

### Preprocessing Directives

Supported directives (processed by the underlying 'preprocess' module):

#### Conditional Blocks

```html
<!-- @if NODE_ENV='production' -->
<script src="analytics.js"></script>
<!-- @endif -->

<!-- @ifdef DEBUG -->
<div class="debug-info">Debug Mode</div>
<!-- @endif -->

<!-- @ifndef PRODUCTION -->
<script src="dev-tools.js"></script>
<!-- @endif -->

Variable Echo

<h1>Version <!-- @echo VERSION --></h1>
<p>Built on <!-- @echo BUILD_DATE --></p>

File Inclusion

<!-- @include header.html -->
<main>Content here</main>
<!-- @include footer.html -->

JavaScript Example

var config = {
  // @if NODE_ENV='development'
  debug: true,
  // @endif
  
  apiUrl: '/* @echo API_URL */' || 'http://localhost:3000'
};

// @ifdef ANALYTICS
trackEvent('page_view');
// @endif

Error Handling

The task includes error handling and logging:

Catches preprocessing errors and logs the problematic source file
Warns about unsafe inline operations
Validates required configuration options
Provides detailed error messages for troubleshooting

Usage Examples

Development vs Production Build

preprocess: {
  options: {
    context: {
      NODE_ENV: process.env.NODE_ENV || 'development'
    }
  },
  build: {
    files: [{
      expand: true,
      cwd: 'src/',
      src: ['**/*.html', '**/*.js'],
      dest: 'dist/'
    }]
  }
}

Custom Context with Functions

preprocess: {
  options: {
    context: {
      VERSION: pkg.version,
      BUILD_DATE: new Date().toISOString(),
      formatPrice: function(price) {
        return '$' + price.toFixed(2);
      }
    }
  },
  templates: {
    src: 'templates/*.html',
    dest: 'build/',
    expand: true
  }
}

Multi-environment Processing

preprocess: {
  dev: {
    options: {
      context: { 
        NODE_ENV: 'development',
        API_URL: 'http://localhost:3000'
      }
    },
    src: 'src/config.js',
    dest: 'build/config.dev.js'
  },
  prod: {
    options: {
      context: { 
        NODE_ENV: 'production',
        API_URL: 'https://api.example.com'
      }
    },
    src: 'src/config.js', 
    dest: 'build/config.prod.js'
  }
}

Types

/**
 * Grunt file configuration object
 */
interface GruntFileConfig {
  src: string | string[];
  dest?: string;
  expand?: boolean;
  cwd?: string;
  ext?: string;
  flatten?: boolean;
}

/**
 * Context object for variable substitution
 */
interface ProcessingContext {
  NODE_ENV?: string;
  [variableName: string]: string | number | boolean | Function | undefined;
}

/**
 * Main preprocessing options (extends options passed to 'preprocess' module)
 */
interface PreprocessingOptions {
  context?: ProcessingContext;
  inline?: boolean;
  srcDir?: string;
  srcEol?: '\n' | '\r\n' | '\r';
  type?: 'html' | 'js' | 'css' | 'coffee' | string;
  fileNotFoundSilentFail?: boolean;
}

/**
 * Complete Grunt instance interface required by grunt-preprocess
 */
interface GruntInstance {
  registerMultiTask(name: string, description: string, taskFunction: Function): void;
  config: {
    requires(property: string): void;
    getRaw(property: string): any;
  };
  file: {
    read(filepath: string): string;
    write(filepath: string, contents: string): void;
  };
  template: {
    process(template: string): string;
  };
  log: {
    error(message: string): void;
    errorlns(message: string): void;
  };
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/grunt-preprocess@5.1.x
Publish Source: CLI
Badge