ignore-styles

ignore-styles is a babel/register style hook that enables Node.js applications to ignore style imports during execution. It prevents Node.js from failing when encountering CSS and other asset imports that are typically handled by bundlers like Webpack, making it essential for testing environments and server-side rendering scenarios.

Package Information

• Package Name: ignore-styles
• Package Type: npm
• Language: JavaScript (ES6 modules transpiled to CommonJS)
• Installation: npm install --save-dev ignore-styles

Core Imports

import register from "ignore-styles";

For named imports:

import register, { DEFAULT_EXTENSIONS, restore, noOp } from "ignore-styles";

For CommonJS:

require("ignore-styles"); // Side-effect import

Or to access specific functions:

const register = require("ignore-styles").default;
const { restore, noOp } = require("ignore-styles");

Basic Usage

The simplest way to use ignore-styles is as a side-effect import, which automatically registers handlers for default file extensions:

// Just importing the module registers default handlers
import "ignore-styles";
// or
require("ignore-styles");

For command-line usage with testing frameworks like Mocha:

mocha --require ignore-styles
mocha --require babel-register --require ignore-styles

Capabilities

Default Registration

Automatically registers handlers for default file extensions when the module is imported.

// Side-effect: register() is called automatically on import
// with DEFAULT_EXTENSIONS and noOp handler

Custom Extension Registration

Register custom file extensions to ignore during Node.js execution.

/**
 * Register handlers for specified file extensions
 * @param extensions - Array of file extensions to ignore, defaults to DEFAULT_EXTENSIONS
 * @param handler - Function to handle ignored imports, defaults to noOp
 */
function register(
  extensions?: string[],
  handler?: (module: any, filename: string) => void
): void;

Usage Examples:

import register from "ignore-styles";

// Register only CSS extensions
register([".css", ".scss", ".sass"]);

// Register with custom handler
register([".css"], (module, filename) => {
  module.exports = { styleName: "test-class" };
});

// Use default extensions with custom handler
register(undefined, (module, filename) => {
  if (filename.endsWith(".png")) {
    module.exports = path.basename(filename);
  }
});

Handler Restoration

Restore require.extensions to their previous state before registration.

/**
 * Restore require.extensions to their state before registration
 * Cleans up all handlers registered by ignore-styles
 */
function restore(): void;

Usage Examples:

import { restore } from "ignore-styles";

// Later in your code, restore original handlers
restore();

Default Extensions

Array of file extensions that are ignored by default.

const DEFAULT_EXTENSIONS: readonly string[];

The default extensions include:

• CSS: .css, .scss, .sass, .pcss, .stylus, .styl, .less, .sss
• Images: .gif, .jpeg, .jpg, .png, .svg
• Videos: .mp4, .webm, .ogv

No-Operation Handler

The default handler function that does nothing when imports are encountered.

/**
 * Default no-operation handler that ignores imports silently
 */
function noOp(): void;

Handler Storage

Object that stores the original require.extensions handlers before modification.

let oldHandlers: Record<string, Function | undefined>;

This is primarily for internal use but can be inspected to see what handlers were replaced.

Types

// Handler function type
type ImportHandler = (module: any, filename: string) => void;

// Extensions array type
type Extensions = string[];

// Old handlers storage type
type OldHandlers = Record<string, Function | undefined>;

Advanced Usage Patterns

Testing with react-css-modules

When using libraries like react-css-modules that expect style imports to return objects:

import register from "ignore-styles";

register(undefined, () => ({ styleName: "mock-class-name" }));

Handling Image Imports in Tests

Return meaningful values for image imports during testing:

import register from "ignore-styles";
import path from "path";

register(undefined, (module, filename) => {
  if ([".png", ".jpg", ".gif"].some(ext => filename.endsWith(ext))) {
    module.exports = path.basename(filename);
  }
});

Conditional Registration

Register handlers only in specific environments:

import register from "ignore-styles";

if (process.env.NODE_ENV === "test") {
  register();
}

Error Handling

ignore-styles operates at the Node.js module system level and does not throw errors under normal circumstances. It gracefully handles:

• Missing original handlers (restored as undefined)
• Duplicate registrations (previous handlers are properly stored)
• Empty extension arrays (no handlers registered)

The package operates by modifying the global require.extensions object, so any issues would manifest as Node.js module loading errors rather than package-specific exceptions.