Grunt Autoprefixer Plugin

Common errors

• Warning: Task 'autoprefixer' not found. Use --force to continue.

  cause The `grunt-autoprefixer` plugin has not been correctly loaded in the Gruntfile, or `npm install` failed to install the package.
  fix Ensure `grunt.loadNpmTasks('grunt-autoprefixer');` is present in your `Gruntfile.js` and run `npm install grunt-autoprefixer --save-dev` to install the plugin.

• Fatal error: Peer dependency `grunt@>=0.4.2` not installed.

  cause The installed version of Grunt does not satisfy the `grunt-autoprefixer` plugin's peer dependency requirement.
  fix Update your `grunt` installation to match the required version, e.g., `npm install grunt@^0.4.2 --save-dev` (adjust version as needed based on the exact peer dependency message).

• No prefixes are being added to my CSS! / Too many prefixes are being added, or old prefixes aren't being removed.

  cause Incorrect or missing `options.browsers` configuration, or `options.remove` is set to `false` when removal is desired, or vice-versa, leading to unexpected prefixing behavior.
  fix Review your `autoprefixer` task options in `Gruntfile.js`, specifically `options.browsers` and `options.remove`. Ensure your `browserslist` query accurately reflects your target browsers. If using `options.map`, ensure it's configured correctly for sourcemap generation.

Warnings

• breaking This package (`grunt-autoprefixer`) is officially deprecated. The maintainers recommend migrating to `grunt-postcss` for future development and active maintenance.
  Fix: Refactor your Gruntfile to use `grunt-postcss` and integrate Autoprefixer as a PostCSS plugin. Install `grunt-postcss` and `autoprefixer` (the PostCSS plugin) and update your Grunt configuration accordingly.
• breaking The `options.remove` property, which controls the removal of outdated vendor prefixes, defaults to `true` since Autoprefixer 4.0.0 (which this plugin likely uses internally). This means old, unnecessary prefixes will be stripped by default, potentially altering CSS output for projects previously relying on `remove: false` implicitly.
  Fix: If you need to preserve outdated prefixes, explicitly set `options.remove: false` in your `autoprefixer` task configuration to override the new default behavior.
• gotcha The `options.browsers` array determines which browsers to target for prefixing. Misconfiguring this option or omitting it can lead to incorrect or insufficient prefixes, or excessive prefixing for unsupported browsers. The default browserlist might not match project requirements.
  Fix: Always explicitly define `options.browsers` in your task configuration or use a `.browserslistrc` file at your project root to ensure accurate targeting. Refer to the `browserslist` documentation for syntax.

Install

• npm install grunt-autoprefixer npm
• yarn add grunt-autoprefixer yarn
• pnpm add grunt-autoprefixer pnpm

Imports

• Task Loading
  wrong:

  const autoprefixer = require('grunt-autoprefixer');

  correct:

  grunt.loadNpmTasks('grunt-autoprefixer');

  Grunt plugins are loaded into the Grunt build system, not imported into application code for direct use.
• Configuration
  wrong:

  grunt.config.set('autoprefixer', { /* ... */ });

  correct:

  grunt.initConfig({
    autoprefixer: { /* ... */ }
  });

  The primary configuration for Grunt tasks like autoprefixer happens within the `initConfig` object in your Gruntfile.

Quickstart

This quickstart demonstrates how to install `grunt-autoprefixer`, integrate it into a `Gruntfile.js`, and configure a basic task to process CSS files from `src/css` and output them to `dist/css` with vendor prefixes applied according to specified browser targets.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    autoprefixer: {
      options: {
        // Specify browsers to target. This can also be done via a .browserslistrc file.
        browsers: ['last 2 versions', 'ie >= 9', 'safari >= 7'],
        cascade: true, // Maintain visual cascade for readability
        remove: true // Remove outdated prefixes
      },
      dist: {
        files: [{
          expand: true,
          cwd: 'src/css/',
          src: '{,*/}*.css',
          dest: 'dist/css/'
        }]
      }
    }
  });

  // Load the plugin that provides the "autoprefixer" task.
  grunt.loadNpmTasks('grunt-autoprefixer');

  // Register a default task.
  grunt.registerTask('default', ['autoprefixer']);

  // To run:
  // 1. npm install grunt grunt-autoprefixer --save-dev
  // 2. Create src/css/style.css with some unprefixed CSS like `display: flex;`
  // 3. Run `npx grunt` in your terminal.
  // 4. Check dist/css/style.css for prefixed output.
};