or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md loader-configuration.md plugin-configuration.md

tile.json

Loader Configuration

Loader configuration methods for ExtractTextPlugin, covering static and instance methods for creating webpack loader configurations that work with the extraction system.

Capabilities

Static Extract Method

Creates an extracting loader configuration that can be used with any ExtractTextPlugin instance.

/**
 * Creates extracting loader configuration (static method)
 * @param {string|array|object} options - Loader configuration
 * @returns {array} Array of loader objects
 */
ExtractTextPlugin.extract(options);

interface ExtractOptions {
  /** Loaders for processing the resource (required) */
  use: string | string[] | object | object[];
  /** Fallback loaders when CSS not extracted */
  fallback?: string | string[] | object | object[];
  /** Override output public path */
  publicPath?: string;
  /** Remove extracted content from bundle */
  remove?: boolean;
  /** Number of loaders to omit from chain */  
  omit?: number;
  /** Plugin instance ID to associate with (for multiple instances) */
  id?: string | number;
}

Usage Examples:

// Basic usage with string loaders
ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: "css-loader"
});

// With loader chain
ExtractTextPlugin.extract({
  fallback: "style-loader", 
  use: ["css-loader", "sass-loader"]
});

// With loader objects
ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: [
    { loader: "css-loader", options: { modules: true } },
    { loader: "sass-loader", options: { sourceMap: true } }
  ]
});

// Shorthand (use only)
ExtractTextPlugin.extract("css-loader");
ExtractTextPlugin.extract(["css-loader", "sass-loader"]);

Static Loader Method

Creates a basic loader configuration object pointing to the ExtractTextPlugin loader.

/**
 * Creates basic loader configuration (static method)
 * @param {object} options - Loader options
 * @returns {object} Loader configuration object with loader and options
 */
ExtractTextPlugin.loader(options);

Usage Examples:

// Basic loader configuration
ExtractTextPlugin.loader({ publicPath: "/assets/" });

// Returns: { loader: "path/to/extract-text-webpack-plugin/loader", options: { publicPath: "/assets/" } }

Extract Options Details

use (required)

Specifies loaders that should be used for converting the resource to CSS. Can be string, array of strings, or loader objects.

// String loader
use: "css-loader"

// Array of string loaders
use: ["css-loader", "sass-loader"]

// Array of loader objects
use: [
  { loader: "css-loader", options: { sourceMap: true } },
  { loader: "sass-loader", options: { sourceMap: true } }
]

// Mixed array
use: [
  "css-loader",
  { loader: "sass-loader", options: { sourceMap: true } }
]

fallback

Specifies loaders to use when the CSS is not extracted (e.g., in development or when allChunks: false).

// String fallback
fallback: "style-loader"

// Array fallback
fallback: ["style-loader", "css-loader"]

// Object fallback
fallback: { loader: "style-loader", options: { sourceMap: true } }

publicPath

Overrides the public path for URLs in the extracted CSS file.

ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: "css-loader",
  publicPath: "/assets/"
});

remove

When true, removes the extracted content from the original module. When false, keeps the content in both places.

ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: "css-loader", 
  remove: true  // Default: true
});

omit

Number of loaders to omit from the beginning of the loader chain.

// Skip first loader in chain
ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: ["postcss-loader", "css-loader", "sass-loader"],
  omit: 1  // Will skip postcss-loader
});

id

Plugin instance ID to associate with when using multiple ExtractTextPlugin instances.

const extractMainCSS = new ExtractTextPlugin({ filename: "main.css", id: "main" });
const extractVendorCSS = new ExtractTextPlugin({ filename: "vendor.css", id: "vendor" });

// Associate extract calls with specific plugin instances
ExtractTextPlugin.extract({
  use: "css-loader",
  id: "main"  // Associates with extractMainCSS instance
});

Advanced Loader Patterns

Conditional Extraction

Extract only in production, use style-loader in development:

const extractCSS = new ExtractTextPlugin({
  filename: "styles.css",
  disable: process.env.NODE_ENV === "development"
});

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: extractCSS.extract({
          fallback: "style-loader",
          use: "css-loader"
        })
      }
    ]
  },
  plugins: process.env.NODE_ENV === "production" ? [extractCSS] : []
};

Source Maps

Enable source maps for extracted CSS:

ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: [
    { loader: "css-loader", options: { sourceMap: true } },
    { loader: "sass-loader", options: { sourceMap: true } }
  ]
});

CSS Modules

Configure CSS Modules with extraction:

ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: [
    { 
      loader: "css-loader", 
      options: { 
        modules: true,
        localIdentName: "[name]__[local]___[hash:base64:5]"
      } 
    }
  ]
});

PostCSS Integration

Combine with PostCSS for autoprefixing and other transforms:

ExtractTextPlugin.extract({
  fallback: "style-loader",
  use: [
    "css-loader",
    {
      loader: "postcss-loader",
      options: {
        plugins: [
          require("autoprefixer")()
        ]
      }
    },
    "sass-loader"
  ]
});

Multiple File Types

Handle different CSS preprocessors:

const extractCSS = new ExtractTextPlugin("[name].css");

module.exports = {
  module: {
    rules: [
      // Plain CSS
      {
        test: /\.css$/,
        use: extractCSS.extract({
          fallback: "style-loader",
          use: "css-loader"
        })
      },
      // SASS/SCSS
      {
        test: /\.s[ac]ss$/,
        use: extractCSS.extract({
          fallback: "style-loader",
          use: ["css-loader", "sass-loader"]
        })
      },
      // LESS
      {
        test: /\.less$/,
        use: extractCSS.extract({
          fallback: "style-loader", 
          use: ["css-loader", "less-loader"]
        })
      }
    ]
  },
  plugins: [extractCSS]
};

Error Handling

The ExtractTextPlugin loader may throw several types of errors during webpack compilation:

Missing Plugin Error: Thrown when the extract loader is used without the corresponding ExtractTextPlugin instance in the webpack plugins array
Child Compilation Errors: Errors from processing extracted content in child webpack compilations
Module Processing Errors: When extracted modules fail to export valid content arrays
File Dependency Errors: Issues with tracking file dependencies during extraction

Common error scenarios:

// Error: Missing plugin
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ExtractTextPlugin.extract("css-loader") // Error: no plugin in plugins array
      }
    ]
  }
  // Missing: plugins: [new ExtractTextPlugin("styles.css")]
};

Loader Functions

The ExtractTextPlugin loader module exports several functions that handle the actual extraction process:

Default Export

The main loader function that processes modules during webpack compilation.

/**
 * Main loader function (processes source content)
 * @param {string} source - Source content being processed
 * @returns {string} Processed source content
 */
function extractTextLoader(source);

Pitch Function

The pitch function that handles extraction logic and child compilation creation.

/**
 * Loader pitch function that handles extraction logic
 * @param {string} request - Webpack request string for the module
 * @returns {string|undefined} Extracted content or undefined for normal processing
 */
function pitch(request);

Note: These loader functions are internal to the webpack loader system and are not typically called directly by user code. They are documented here for completeness of the API surface.

Version

Tile

Files