Preprocess Loader

0.3.0 verified Sat Apr 25 auth: no javascript maintenance

A webpack loader that uses the preprocess library to conditionally include or exclude code in HTML, JavaScript, CoffeeScript, and other module files based on custom or environment configurations. Version 0.3.0 is the latest stable release (the project appears inactive since 2017). It supports Webpack 1 and 2+ and allows overriding preprocess options via the `ppOptions` query parameter. Similar to gulp-preprocess, it provides directive syntax for conditional compilation (@if, @ifdef, @echo, @include). The loader is typically placed before other loaders in a chain to preprocess files before they are transpiled.

Common errors

error Cannot find module 'preprocess-loader' ↓

cause Missing npm install or not installed as devDependency.

fix

Run npm install preprocess-loader --save-dev or yarn add preprocess-loader --dev.

error Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Using Webpack 2+ with the old `loaders` array instead of `rules`.

fix

Replace module.loaders with module.rules and loader with use.

error Module build failed: Error: You may need an appropriate loader to handle this file type. ↓

cause preprocess-loader is not in the loader chain or is placed after a loader that removes comments.

fix

Add preprocess-loader to the use array before other loaders (e.g., before babel-loader).

Warnings

gotcha Loader chain ordering matters: preprocess-loader should run before other loaders (e.g., babel-loader) to avoid preprocessed comments being transpiled away. ↓

fix Place preprocess-loader earlier in the `use` array (right-to-left execution).

gotcha Directives inside @echo blocks may not be processed in coffee/shell type unless you apply a second preprocess pass after compilation. ↓

fix Chain two preprocess loaders: one with type:'cjsx' before CoffeeScript loader, one with type:'js' after.

deprecated Webpack 1 style `loaders` array with query strings is deprecated in Webpack 2+. ↓

fix Use `rules` with `use` array and `options` object.

breaking Upgrade from v0.1.0 to v0.2.0 updated preprocess from v2 to v3, which may change behavior of some directives. ↓

fix Check preprocess v3 release notes for breaking changes; update your code if necessary.

Install

npm install preprocess-loader

yarn add preprocess-loader

pnpm add preprocess-loader

Imports

default
wrong
```
const PreprocessLoader = require('preprocess-loader')
```
correct
```
import PreprocessLoader from 'preprocess-loader'
```
As a webpack loader, it is not typically imported directly; it is configured in webpack.config via loader name string 'preprocess-loader'. The import pattern is uncommon but shown for completeness.

useLoader

wrong

module.exports = { module: { loaders: [ { test: /\.js$/, loader: 'preprocess-loader?+DEBUG' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.js$/, use: 'preprocess-loader?+DEBUG' } ] } }

Webpack 2+ uses `rules` and `use` instead of `loaders`. The old `loaders` array is deprecated.

queryOptions

wrong

use: [ { loader: 'preprocess-loader?DEBUG=true&NODE_ENV=production' } ]

correct

use: [ { loader: 'preprocess-loader', options: { DEBUG: true, NODE_ENV: 'production' } } ]

Webpack 2+ supports the `options` object. Query string may still work but is less maintainable.

Quickstart

Webpack 2+ configuration using preprocess-loader with environment variables and Babel.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'preprocess-loader',
            options: {
              DEBUG: process.env.DEBUG === 'true' ? true : false,
              NODE_ENV: process.env.NODE_ENV ?? 'production'
            }
          },
          'babel-loader'
        ]
      }
    ]
  }
};

// In your source.js
const configValue = '/* @echo FOO */' || 'default value';

// @ifdef DEBUG
console.log('Debugging enabled');
// @endif