0
# ignore-styles
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: ignore-styles
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6 modules transpiled to CommonJS)
9
- **Installation**: `npm install --save-dev ignore-styles`
10

11
## Core Imports
12

13
```javascript
14
import register from "ignore-styles";
15
```
16

17
For named imports:
18

19
```javascript
20
import register, { DEFAULT_EXTENSIONS, restore, noOp } from "ignore-styles";
21
```
22

23
For CommonJS:
24

25
```javascript
26
require("ignore-styles"); // Side-effect import
27
```
28

29
Or to access specific functions:
30

31
```javascript
32
const register = require("ignore-styles").default;
33
const { restore, noOp } = require("ignore-styles");
34
```
35

36
## Basic Usage
37

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

40
```javascript
41
// Just importing the module registers default handlers
42
import "ignore-styles";
43
// or
44
require("ignore-styles");
45
```
46

47
For command-line usage with testing frameworks like Mocha:
48

49
```bash
50
mocha --require ignore-styles
51
mocha --require babel-register --require ignore-styles
52
```
53

54
## Capabilities
55

56
### Default Registration
57

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

60
```javascript { .api }
61
// Side-effect: register() is called automatically on import
62
// with DEFAULT_EXTENSIONS and noOp handler
63
```
64

65
### Custom Extension Registration
66

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

69
```javascript { .api }
70
/**
71
 * Register handlers for specified file extensions
72
 * @param extensions - Array of file extensions to ignore, defaults to DEFAULT_EXTENSIONS
73
 * @param handler - Function to handle ignored imports, defaults to noOp
74
 */
75
function register(
76
  extensions?: string[],
77
  handler?: (module: any, filename: string) => void
78
): void;
79
```
80

81
**Usage Examples:**
82

83
```javascript
84
import register from "ignore-styles";
85

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

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

94
// Use default extensions with custom handler
95
register(undefined, (module, filename) => {
96
  if (filename.endsWith(".png")) {
97
    module.exports = path.basename(filename);
98
  }
99
});
100
```
101

102
### Handler Restoration
103

104
Restore require.extensions to their previous state before registration.
105

106
```javascript { .api }
107
/**
108
 * Restore require.extensions to their state before registration
109
 * Cleans up all handlers registered by ignore-styles
110
 */
111
function restore(): void;
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
import { restore } from "ignore-styles";
118

119
// Later in your code, restore original handlers
120
restore();
121
```
122

123
### Default Extensions
124

125
Array of file extensions that are ignored by default.
126

127
```javascript { .api }
128
const DEFAULT_EXTENSIONS: readonly string[];
129
```
130

131
The default extensions include:
132
- **CSS**: `.css`, `.scss`, `.sass`, `.pcss`, `.stylus`, `.styl`, `.less`, `.sss`
133
- **Images**: `.gif`, `.jpeg`, `.jpg`, `.png`, `.svg`
134
- **Videos**: `.mp4`, `.webm`, `.ogv`
135

136
### No-Operation Handler
137

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

140
```javascript { .api }
141
/**
142
 * Default no-operation handler that ignores imports silently
143
 */
144
function noOp(): void;
145
```
146

147
### Handler Storage
148

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

151
```javascript { .api }
152
let oldHandlers: Record<string, Function | undefined>;
153
```
154

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

157
## Types
158

159
```javascript { .api }
160
// Handler function type
161
type ImportHandler = (module: any, filename: string) => void;
162

163
// Extensions array type
164
type Extensions = string[];
165

166
// Old handlers storage type
167
type OldHandlers = Record<string, Function | undefined>;
168
```
169

170
## Advanced Usage Patterns
171

172
### Testing with react-css-modules
173

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

176
```javascript
177
import register from "ignore-styles";
178

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

182
### Handling Image Imports in Tests
183

184
Return meaningful values for image imports during testing:
185

186
```javascript
187
import register from "ignore-styles";
188
import path from "path";
189

190
register(undefined, (module, filename) => {
191
  if ([".png", ".jpg", ".gif"].some(ext => filename.endsWith(ext))) {
192
    module.exports = path.basename(filename);
193
  }
194
});
195
```
196

197
### Conditional Registration
198

199
Register handlers only in specific environments:
200

201
```javascript
202
import register from "ignore-styles";
203

204
if (process.env.NODE_ENV === "test") {
205
  register();
206
}
207
```
208

209
## Error Handling
210

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

213
- Missing original handlers (restored as undefined)
214
- Duplicate registrations (previous handlers are properly stored)
215
- Empty extension arrays (no handlers registered)
216

217
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.