0
# Stringify
1

2
Stringify is a Browserify transform middleware that enables requiring text files (including HTML templates, Handlebars templates, and other text-based assets) directly inside client-side JavaScript files as strings. The package also provides Node.js integration for server-side usage and comprehensive HTML minification capabilities.
3

4
## Package Information
5

6
- **Package Name**: stringify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install stringify`
10

11
## Core Imports
12

13
```javascript
14
const stringify = require('stringify');
15
```
16

17
For ES modules:
18

19
```javascript
20
import stringify from 'stringify';
21
```
22

23
## Basic Usage
24

25
### Browserify Transform
26

27
```javascript
28
const browserify = require('browserify');
29
const stringify = require('stringify');
30

31
const bundle = browserify()
32
  .transform(stringify, {
33
    appliesTo: { includeExtensions: ['.html', '.hbs', '.txt'] }
34
  })
35
  .add('my_app_main.js');
36
```
37

38
Then in your client-side code:
39

40
```javascript
41
const template = require('./path/to/template.html');
42
console.log(template); // String content of the HTML file
43
```
44

45
### Node.js Require Registration
46

47
```javascript
48
const stringify = require('stringify');
49

50
stringify.registerWithRequire({
51
  appliesTo: { includeExtensions: ['.txt', '.html'] },
52
  minify: true
53
});
54

55
const textFile = require('./data.txt');
56
console.log(textFile); // String content of the text file
57
```
58

59
## Capabilities
60

61
### Browserify Transform Function
62

63
Main export that handles Browserify transformations with two usage patterns: factory mode and standard mode.
64

65
```javascript { .api }
66
/**
67
 * Browserify transform function with dual usage patterns
68
 * @param {string|object|array} file - File path (standard mode) or options (factory mode)
69
 * @param {object|array} options - Transform options (standard mode only)
70
 * @returns {Stream|Function} Transform stream (standard) or factory function
71
 */
72
function stringify(file, options);
73
```
74

75
**Factory Mode** (returns transform function):
76
- `stringify()` - Uses default options
77
- `stringify(options)` - Uses specified options
78

79
**Standard Mode** (returns transform stream):
80
- `stringify(file, options)` - Transforms specific file with options
81

82
### Node.js Require Registration
83

84
Registers file extensions with Node.js require system to enable requiring text files.
85

86
```javascript { .api }
87
/**
88
 * Registers extensions with Node.js require to load text files as strings
89
 * @param {object|array} options - Configuration options for extensions and minification
90
 * @returns {void}
91
 */
92
function registerWithRequire(options);
93
```
94

95
## Configuration Options
96

97
### File Matching Configuration
98

99
The `appliesTo` option controls which files are processed:
100

101
```javascript { .api }
102
interface AppliesTo {
103
  /** Array of file extensions to include (e.g., ['.html', '.txt']) */
104
  includeExtensions?: string[];
105
  /** Array of file extensions to exclude */
106
  excludeExtensions?: string[];
107
  /** Array of specific file paths to process */
108
  files?: string[];
109
  /** Regex pattern(s) for file matching */
110
  regex?: RegExp | RegExp[];
111
}
112
```
113

114
### Transform Options
115

116
```javascript { .api }
117
interface TransformOptions {
118
  /** File matching configuration */
119
  appliesTo?: AppliesTo;
120
  /** Enable HTML minification */
121
  minify?: boolean;
122
  /** File matching for minification (separate from appliesTo) */
123
  minifyAppliesTo?: AppliesTo;
124
  /** HTML minifier options */
125
  minifyOptions?: MinifyOptions;
126
}
127
```
128

129
### Minification Options
130

131
```javascript { .api }
132
interface MinifyOptions {
133
  /** Remove HTML comments */
134
  removeComments?: boolean;
135
  /** Remove comments from CDATA sections */
136
  removeCommentsFromCDATA?: boolean;
137
  /** Remove CDATA sections from CDATA sections */
138
  removeCDATASectionsFromCDATA?: boolean;
139
  /** Collapse whitespace */
140
  collapseWhitespace?: boolean;
141
  /** Conservative whitespace collapse */
142
  conservativeCollapse?: boolean;
143
  /** Preserve line breaks */
144
  preserveLineBreaks?: boolean;
145
  /** Collapse boolean attributes */
146
  collapseBooleanAttributes?: boolean;
147
  /** Remove attribute quotes when safe */
148
  removeAttributeQuotes?: boolean;
149
  /** Remove redundant attributes */
150
  removeRedundantAttributes?: boolean;
151
  /** Use short DOCTYPE */
152
  useShortDoctype?: boolean;
153
  /** Remove empty attributes */
154
  removeEmptyAttributes?: boolean;
155
  /** Remove script type attributes */
156
  removeScriptTypeAttributes?: boolean;
157
  /** Remove style link type attributes */
158
  removeStyleLinkTypeAttributes?: boolean;
159
  /** Remove optional tags */
160
  removeOptionalTags?: boolean;
161
  /** Remove ignored elements */
162
  removeIgnored?: boolean;
163
  /** Remove empty elements */
164
  removeEmptyElements?: boolean;
165
  /** Enable linting */
166
  lint?: boolean;
167
  /** Keep closing slash for self-closing tags */
168
  keepClosingSlash?: boolean;
169
  /** Case sensitive processing */
170
  caseSensitive?: boolean;
171
  /** Minify inline JavaScript */
172
  minifyJS?: boolean;
173
  /** Minify inline CSS */
174
  minifyCSS?: boolean;
175
  /** Minify URLs */
176
  minifyURLs?: boolean;
177
}
178
```
179

180
## Test Environment Exports
181

182
Additional functions and constants are conditionally exported when `NODE_ENV` environment variable is set, primarily for testing and debugging purposes.
183

184
### Internal Functions
185

186
```javascript { .api }
187
/**
188
 * Global state object for Node.js require options
189
 */
190
const NODE_REQUIRE_OPTIONS: object;
191

192
/**
193
 * Internal function to handle file stringification for Node.js require
194
 * @param {object} module - Module object
195
 * @param {string} filename - File path to read and stringify
196
 * @returns {void}
197
 */
198
function requireStringify(module: object, filename: string): void;
199

200
/**
201
 * Internal string conversion function
202
 * @param {string} content - Content to stringify
203
 * @returns {string} Module export string format
204
 */
205
function stringify(content: string): string;
206

207
/**
208
 * Gets extensions for Node.js require registration
209
 * @param {object|array} options - Configuration options
210
 * @returns {string[]} Array of lowercase file extensions
211
 */
212
function getRequireExtensions(options?: object | array): string[];
213

214
/**
215
 * Normalizes user-supplied options for browserify-transform-tools
216
 * @param {object|array} options - User options
217
 * @returns {object} Normalized transform options
218
 */
219
function getTransformOptions(options?: object | array): object;
220

221
/**
222
 * Handles file minification logic
223
 * @param {string} filename - File being processed
224
 * @param {string} contents - File contents
225
 * @param {object} options - Minification options
226
 * @returns {string} Minified or original contents
227
 */
228
function minify(filename: string, contents: string, options: object): string;
229

230
/**
231
 * Determines minification configuration from user options
232
 * @param {object} options - User-supplied options
233
 * @returns {object} Minification configuration object
234
 */
235
function getMinifyOptions(options: object): object;
236
```
237

238
### Configuration Constants
239

240
```javascript { .api }
241
/**
242
 * Default transform options for file matching
243
 */
244
const TRANSFORM_OPTIONS: {
245
  includeExtensions: string[];
246
};
247

248
/**
249
 * Default minification transform options
250
 */
251
const MINIFY_TRANSFORM_OPTIONS: {
252
  includeExtensions: string[];
253
};
254

255
/**
256
 * Default HTML minifier options
257
 */
258
const DEFAULT_MINIFY_OPTIONS: {
259
  removeComments: boolean;
260
  removeCommentsFromCDATA: boolean;
261
  removeCDATASectionsFromCDATA: boolean;
262
  collapseWhitespace: boolean;
263
  conservativeCollapse: boolean;
264
  preserveLineBreaks: boolean;
265
  collapseBooleanAttributes: boolean;
266
  removeAttributeQuotes: boolean;
267
  removeRedundantAttributes: boolean;
268
  useShortDoctype: boolean;
269
  removeEmptyAttributes: boolean;
270
  removeScriptTypeAttributes: boolean;
271
  removeStyleLinkTypeAttributes: boolean;
272
  removeOptionalTags: boolean;
273
  removeIgnored: boolean;
274
  removeEmptyElements: boolean;
275
  lint: boolean;
276
  keepClosingSlash: boolean;
277
  caseSensitive: boolean;
278
  minifyJS: boolean;
279
  minifyCSS: boolean;
280
  minifyURLs: boolean;
281
};
282
```
283

284
## Default File Extensions
285

286
### Transform Extensions
287
Default extensions processed by stringify:
288
```javascript
289
['.html', '.htm', '.tmpl', '.tpl', '.hbs', '.text', '.txt']
290
```
291

292
### Minification Extensions
293
Default extensions processed by HTML minifier:
294
```javascript
295
['.html', '.htm', '.tmpl', '.tpl', '.hbs']
296
```
297

298
## Usage Examples
299

300
### Command Line Usage
301

302
```bash
303
browserify -t [ stringify --extensions [.html .hbs] ] myfile.js
304
```
305

306
### Gulp Integration
307

308
```javascript
309
const gulp = require('gulp');
310
const browserify = require('browserify');
311
const source = require('vinyl-source-stream');
312
const stringify = require('stringify');
313

314
gulp.task('js', function() {
315
  return browserify({ entries: ['src/main.js'] })
316
    .transform(stringify, {
317
      appliesTo: { includeExtensions: ['.html'] },
318
      minify: true
319
    })
320
    .bundle()
321
    .pipe(source('main.js'))
322
    .pipe(gulp.dest('dist'));
323
});
324
```
325

326
### Advanced Minification Configuration
327

328
```javascript
329
const stringify = require('stringify');
330

331
const bundle = browserify()
332
  .transform(stringify, {
333
    appliesTo: { includeExtensions: ['.html', '.hbs', '.txt'] },
334
    minify: true,
335
    minifyAppliesTo: { includeExtensions: ['.html', '.hbs'] },
336
    minifyOptions: {
337
      removeComments: true,
338
      collapseWhitespace: true,
339
      removeAttributeQuotes: true,
340
      minifyJS: true,
341
      minifyCSS: true
342
    }
343
  })
344
  .add('app.js');
345
```
346

347
### Handlebars Template Integration
348

349
```javascript
350
// Client-side application code
351
const Handlebars = require('handlebars');
352
const template = require('./templates/user-card.hbs');
353

354
const compiledTemplate = Handlebars.compile(template);
355
const html = compiledTemplate({
356
  name: 'John Doe',
357
  email: 'john@example.com'
358
});
359

360
document.body.innerHTML = html;
361
```
362

363
## Error Handling
364

365
### Common Errors
366

367
- **File Not Found**: When `require()` references a non-existent file, stringify throws an error with the full resolved path
368
- **Transform Failures**: Invalid configuration or file processing errors are passed through browserify-transform-tools
369
- **Minification Errors**: Invalid HTML that cannot be minified will cause transform failures
370

371
### Error Example
372

373
```javascript
374
// This will throw: "Stringify could not find module '/absolute/path/to/missing.txt'"
375
const missingFile = require('./missing.txt');
376
```
377

378
## Version Compatibility
379

380
- **Node.js**: Requires Node.js >= 4.0.0
381
- **Browserify**: Compatible with all standard browserify versions
382
- **Testing**: Verified up to Node.js 8.1.3