or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Grunt Webpack

Grunt Webpack is a Grunt plugin that integrates webpack into Grunt-based build workflows. It provides two main tasks: 'webpack' for production builds and 'webpack-dev-server' for development workflows, with comprehensive configuration options that mirror webpack's native configuration structure.

Package Information

  • Package Name: grunt-webpack
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install webpack grunt-webpack --save-dev

Core Imports

The plugin is loaded using Grunt's standard task loading mechanism:

// In your Gruntfile.js
grunt.loadNpmTasks('grunt-webpack');

Basic Usage

const webpackConfig = require('./webpack.config.js');

module.exports = function(grunt) {
  grunt.initConfig({
    webpack: {
      prod: webpackConfig,
      dev: Object.assign({ watch: true }, webpackConfig)
    },
    'webpack-dev-server': {
      dev: webpackConfig
    }
  });

  grunt.loadNpmTasks('grunt-webpack');
};

Architecture

Grunt Webpack consists of:

  • Task Registration: Two main Grunt tasks (webpack, webpack-dev-server) that integrate with Grunt's task system
  • Option Helpers: Classes that handle configuration merging, template processing, and validation
  • Progress Integration: Built-in webpack progress reporting for Grunt output
  • Configuration Processing: Support for lazy loading, promises, and Grunt template interpolation

Capabilities

Webpack Build Task

Runs webpack compilation with full configuration support and Grunt-specific options.

// Task configuration
grunt.config('webpack', {
  [target: string]: WebpackConfiguration | Function | Promise<WebpackConfiguration>
});

// Grunt-specific options
interface GruntWebpackOptions {
  /** Terminate grunt process on webpack errors (default: true, false if watch mode) */
  failOnError?: boolean;
  /** Keep grunt process alive after webpack completion (default: false, true if watch mode) */
  keepalive?: boolean;
  /** Show webpack progress output (default: true if TTY present) */
  progress?: boolean;
  /** Store webpack stats to grunt config variable */
  storeStatsTo?: string;
  /** Enable webpack watch mode */
  watch?: boolean;
  /** Webpack stats configuration options */
  stats?: webpack.Configuration['stats'];
}

Usage Examples:

// Basic configuration
grunt.initConfig({
  webpack: {
    prod: {
      entry: './src/index.js',
      output: {
        path: __dirname + '/dist',
        filename: 'bundle.js'
      }
    }
  }
});

// With grunt-specific options
grunt.initConfig({
  webpack: {
    options: {
      stats: !process.env.NODE_ENV || process.env.NODE_ENV === 'development'
    },
    prod: webpackConfig,
    dev: Object.assign({ 
      watch: true,
      keepalive: true,
      failOnError: false 
    }, webpackConfig)
  }
});

Webpack Dev Server Task

Starts webpack development server with full webpack-dev-server configuration support.

// Task configuration
grunt.config('webpack-dev-server', {
  [target: string]: WebpackConfiguration & { devServer?: WebpackDevServer.Configuration }
});

// Default dev server options
interface DefaultDevServerOptions {
  /** Default host for webpack-dev-server (default: "localhost") */
  devServer: {
    host: string;
  };
  /** Progress output (default: true if TTY present) */
  progress?: boolean;
  /** Webpack stats configuration */
  stats?: webpack.Configuration['stats'];
}

Usage Examples:

// Basic dev server configuration
grunt.initConfig({
  'webpack-dev-server': {
    dev: {
      entry: './src/index.js',
      output: {
        path: __dirname + '/dist',
        filename: 'bundle.js'
      },
      devServer: {
        host: 'localhost',
        port: 8080,
        open: true
      }
    }
  }
});

Lazy Configuration Loading

Support for dynamic configuration loading through functions and promises.

// Function-based configuration
type ConfigFunction = (gruntConfig: any) => webpack.Configuration;

// Promise-based configuration  
type ConfigPromise = Promise<webpack.Configuration>;

Usage Examples:

// Lazy configuration with function
grunt.initConfig({
  webpack: {
    myconfig: () => ({
      entry: path.join(__dirname, 'entry'),
      output: {
        path: __dirname,
        filename: 'output.js'
      }
    })
  }
});

// Promise-based configuration
grunt.initConfig({
  webpack: {
    myconfig: Promise.resolve(webpackConfig)
  }
});

// Function with access to grunt configuration
grunt.initConfig({
  name: 'MyApp',
  webpack: {
    myconfig: (config) => ({
      entry: './src/index.js',
      plugins: [
        new webpack.BannerPlugin({
          banner: `/* ${config.name} - Built ${grunt.template.today()} */`
        })
      ]
    })
  }
});

Grunt Template Support

All string values in webpack configuration support Grunt template interpolation.

// Template interpolation in configuration
interface TemplateSupport {
  /** Any string value can use Grunt templates like "<%= variable %>" */
  [key: string]: string | TemplateSupport;
}

Usage Examples:

grunt.initConfig({
  outputFileName: 'bundle.js',
  webpack: {
    myconfig: {
      entry: './src/index.js',
      output: {
        path: __dirname + '/dist',
        filename: '<%= outputFileName %>'
      }
    }
  }
});

Stats Storage

Store webpack compilation statistics in Grunt configuration for use in other tasks.

// Stats storage configuration
interface StatsStorage {
  /** Variable name to store webpack stats */
  storeStatsTo: string;
}

// Stored stats structure (webpack.Stats.toJson() result)
interface StoredStats {
  hash: string;
  version: string;
  time: number;
  assets: Array<{
    name: string;
    size: number;
  }>;
  // ... other webpack stats properties
}

Usage Examples:

grunt.initConfig({
  webpack: {
    prod: {
      // webpack config...
      storeStatsTo: 'webpackStats'
    }
  },
  // Use stored stats in other tasks
  copy: {
    assets: {
      src: 'assets/**',
      dest: 'dist/<%= webpackStats.hash %>/'
    }
  }
});

Error Handling

The plugin handles webpack compilation errors and integrates them with Grunt's error reporting system.

Common Error Scenarios:

  • No Configuration Found: Throws error if no webpack configuration is provided for any target
  • Webpack Compilation Errors: Displays webpack error output and optionally terminates grunt process based on failOnError setting
  • Missing webpack-dev-server: Shows helpful installation message if webpack-dev-server task is used without the package installed

Command Line Usage

# Run webpack with specific target
grunt webpack:prod

# Run webpack with all targets
grunt webpack

# Run webpack-dev-server
grunt webpack-dev-server:dev

# Run with environment variables
NODE_ENV=production grunt webpack:prod

Types

/** Webpack configuration object or function/promise returning configuration */
type WebpackConfiguration = webpack.Configuration | ConfigFunction | ConfigPromise;

/** Function that receives grunt configuration and returns webpack config */
type ConfigFunction = (gruntConfig: any) => webpack.Configuration;

/** Promise resolving to webpack configuration */
type ConfigPromise = Promise<webpack.Configuration>;

/** Grunt task configuration structure */
interface GruntTaskConfig {
  /** Shared options for all targets */
  options?: GruntWebpackOptions;
  /** Named targets with individual configurations */
  [targetName: string]: WebpackConfiguration | GruntWebpackOptions;
}

/** Complete grunt-webpack configuration interface */
interface GruntWebpackConfiguration {
  webpack?: GruntTaskConfig;
  'webpack-dev-server'?: GruntTaskConfig;
}