0
# Command Line Interface
1

2
Command-line tools for template compilation, file watching, and build integration through the `dustc` binary.
3

4
## Capabilities
5

6
### Basic Usage
7

8
The `dustc` command-line compiler for pre-compiling Dust templates to JavaScript.
9

10
```bash { .api }
11
# Basic command syntax
12
dustc [options] [path1 [path2 path3...]]
13

14
# Installation provides global binary
15
npm install dustjs-linkedin
16
# Binary available at: node_modules/.bin/dustc
17
```
18

19
**Usage Examples:**
20

21
```bash
22
# Compile single template
23
dustc templates/user.dust
24

25
# Compile multiple templates
26
dustc templates/header.dust templates/footer.dust templates/main.dust
27

28
# Compile all templates in directory
29
dustc templates/*.dust
30

31
# Use glob patterns
32
dustc templates/**/*.dust
33
```
34

35
### Command Options
36

37
Comprehensive set of options for controlling compilation behavior and output format.
38

39
```bash { .api }
40
# Template naming
41
-n, --name <string>         # Template name for single file compilation
42

43
# Output control
44
-o, --output <path>         # Concatenate all output to this file
45
-s, --split                 # Create separate output files per input
46

47
# Path handling
48
--pwd <string>              # Base directory for template names
49

50
# Formatting
51
-w, --whitespace           # Preserve whitespace in templates
52

53
# Module formats
54
-a, --amd                  # Output AMD modules
55
--cjs                      # Output CommonJS modules (auto-enables --split)
56

57
# Development
58
--watch                    # Watch files for changes and recompile
59
```
60

61
**Usage Examples:**
62

63
```bash
64
# Compile with custom name
65
dustc -n "greeting" templates/hello.dust
66

67
# Concatenate multiple files
68
dustc --output=compiled.js templates/*.dust
69

70
# Create separate output files
71
dustc --split templates/*.dust
72

73
# Set base directory for template names
74
dustc --pwd=templates templates/user/*.dust
75

76
# Preserve whitespace
77
dustc -w templates/formatted.dust
78

79
# Generate AMD modules
80
dustc -a --split templates/*.dust
81

82
# Generate CommonJS modules (automatically splits)
83
dustc --cjs templates/*.dust
84

85
# Watch for changes during development
86
dustc --watch --split templates/**/*.dust
87
```
88

89
### Standard Input Support
90

91
Support for piping template content through stdin for integration with build tools.
92

93
```bash { .api }
94
# Read from stdin
95
echo "Hello {name}!" | dustc -n "greeting"
96

97
# Pipe from other commands
98
cat template.dust | dustc -n "template"
99

100
# No template name (creates anonymous template)
101
echo "{message}" | dustc
102
```
103

104
**Usage Examples:**
105

106
```bash
107
# Compile template from stdin
108
echo "Welcome {user.name}!" | dustc -n "welcome" > welcome.js
109

110
# Process template through pipeline
111
curl https://templates.example.com/header.dust | dustc -n "header" -a > header-amd.js
112

113
# Batch processing with build tools
114
find templates -name "*.dust" -exec cat {} \; | dustc -n "combined"
115
```
116

117
## Output Formats
118

119
### Default JavaScript Output
120

121
Standard compiled JavaScript output format for direct loading.
122

123
```bash { .api }
124
# Default output format
125
dustc templates/example.dust
126

127
# Produces JavaScript like:
128
# (function(){dust.register("example",body_0);function body_0(chk,ctx){...}})();
129
```
130

131
**Usage Examples:**
132

133
```bash
134
# Compile to default format
135
dustc templates/user-profile.dust > user-profile.js
136

137
# Load in Node.js
138
dust.loadSource(fs.readFileSync('user-profile.js', 'utf8'));
139

140
# Load in browser
141
<script src="user-profile.js"></script>
142
```
143

144
### AMD Module Output
145

146
Generate AMD (Asynchronous Module Definition) compatible modules.
147

148
```bash { .api }
149
# Generate AMD modules
150
dustc -a templates/*.dust
151

152
# Produces AMD modules like:
153
# define("dust-template-name", ["dust"], function(dust) {
154
#   dust.register("template-name", body_0);
155
#   function body_0(chk,ctx){...}
156
#   return "template-name";
157
# });
158
```
159

160
**Usage Examples:**
161

162
```bash
163
# Generate AMD modules with split output
164
dustc -a --split templates/*.dust
165

166
# Use with RequireJS
167
require(['dust-template-user'], function(templateName) {
168
  dust.render(templateName, userData, callback);
169
});
170

171
# Build system integration
172
dustc -a --output=dist/templates.js src/templates/**/*.dust
173
```
174

175
### CommonJS Module Output
176

177
Generate CommonJS modules for Node.js and bundlers.
178

179
```bash { .api }
180
# Generate CommonJS modules (automatically enables --split)
181
dustc --cjs templates/*.dust
182

183
# Produces CommonJS modules like:
184
# var dust = require("dustjs-linkedin");
185
# dust.register("template-name", body_0);
186
# function body_0(chk,ctx){...}
187
# module.exports = "template-name";
188
```
189

190
**Usage Examples:**
191

192
```bash
193
# Generate CommonJS modules
194
dustc --cjs templates/*.dust
195

196
# Use in Node.js
197
const templateName = require('./templates/user.js');
198
dust.render(templateName, userData, callback);
199

200
# Use with bundlers (Webpack, Browserify)
201
const userTemplate = require('./templates/user.js');
202
```
203

204
## File Watching
205

206
### Development Mode
207

208
Watch templates for changes and automatically recompile during development.
209

210
```bash { .api }
211
# Enable file watching
212
dustc --watch [other-options] templates/**/*.dust
213

214
# Watch with specific output configuration
215
dustc --watch --split --output-dir=compiled templates/*.dust
216
```
217

218
**Usage Examples:**
219

220
```bash
221
# Watch and recompile on changes
222
dustc --watch --split templates/**/*.dust
223

224
# Watch with AMD output
225
dustc --watch -a --split templates/*.dust
226

227
# Development server integration
228
dustc --watch --cjs --output=dist/templates/ src/templates/**/*.dust &
229
node server.js
230
```
231

232
## Template Naming
233

234
### Automatic Naming
235

236
How `dustc` automatically generates template names from file paths.
237

238
```bash { .api }
239
# Automatic naming rules:
240
# templates/user/profile.dust -> "user/profile"
241
# src/views/header.dust -> "views/header"
242
# main.dust -> "main"
243

244
# Control base path with --pwd
245
dustc --pwd=templates templates/user/profile.dust
246
# Results in template name: "user/profile"
247

248
dustc --pwd=src src/views/header.dust
249
# Results in template name: "views/header"
250
```
251

252
**Usage Examples:**
253

254
```bash
255
# Default naming (includes directory structure)
256
dustc templates/components/header.dust
257
# Template name: "templates/components/header"
258

259
# Set base directory
260
dustc --pwd=templates templates/components/header.dust
261
# Template name: "components/header"
262

263
# Single file with explicit name
264
dustc -n "app-header" templates/components/header.dust
265
# Template name: "app-header"
266
```
267

268
### Custom Naming
269

270
Override automatic naming with explicit template names.
271

272
```bash { .api }
273
# Single template with custom name
274
dustc -n "custom-name" template.dust
275

276
# Note: --name only works with single input file
277
# For multiple files, use --pwd to control automatic naming
278
```
279

280
## Integration Examples
281

282
### Build System Integration
283

284
Examples of integrating `dustc` with various build systems.
285

286
```bash
287
# Makefile integration
288
templates: $(DUST_FILES)
289
	dustc --split --output-dir=dist/templates/ src/templates/**/*.dust
290

291
# NPM scripts
292
{
293
  "scripts": {
294
    "build:templates": "dustc --cjs --split src/templates/**/*.dust",
295
    "dev:templates": "dustc --watch --cjs --split src/templates/**/*.dust",
296
    "build": "npm run build:templates && webpack"
297
  }
298
}
299

300
# Gulp integration
301
gulp.task('templates', () => {
302
  return exec('dustc --amd --split src/templates/**/*.dust');
303
});
304

305
# Webpack integration (as npm script)
306
"prebuild": "dustc --cjs --split src/templates/**/*.dust"
307
```
308

309
### CI/CD Pipeline Integration
310

311
Using `dustc` in continuous integration and deployment pipelines.
312

313
```bash
314
# GitHub Actions
315
- name: Compile Dust templates
316
  run: |
317
    dustc --cjs --split src/templates/**/*.dust
318
    ls -la templates/
319

320
# Docker build
321
RUN npm install dustjs-linkedin && \
322
    dustc --cjs --split templates/**/*.dust && \
323
    rm -rf node_modules
324

325
# Production build script
326
#!/bin/bash
327
set -e
328
echo "Compiling Dust templates..."
329
dustc --amd --output=dist/templates.js src/templates/**/*.dust
330
echo "Templates compiled successfully"
331
```
332

333
## Error Handling and Debugging
334

335
### Compilation Errors
336

337
How `dustc` reports template compilation errors.
338

339
```bash
340
# Syntax errors include file and line information
341
dustc templates/broken.dust
342
# Error: Template syntax error in templates/broken.dust:5:12
343
# Expected closing tag but found EOF
344

345
# Missing file errors
346
dustc non-existent.dust
347
# Error: ENOENT: no such file or directory, open 'non-existent.dust'
348
```
349

350
### Verbose Output
351

352
Getting detailed information during compilation.
353

354
```bash
355
# Use Node.js DEBUG environment variable
356
DEBUG=dust dustc templates/*.dust
357

358
# Enable verbose logging
359
NODE_ENV=development dustc templates/*.dust
360

361
# Check compiled output
362
dustc templates/test.dust && cat test.js
363
```
364

365
### Common Issues and Solutions
366

367
Troubleshooting common `dustc` usage problems.
368

369
```bash
370
# Issue: Templates not found at runtime
371
# Solution: Ensure template names match registration
372
dustc --pwd=templates templates/user.dust  # Creates "user" template
373
dust.render("user", data, callback);       # Correct reference
374

375
# Issue: Module format compatibility
376
# Solution: Match output format to usage environment
377
dustc --cjs templates/*.dust              # For Node.js/bundlers
378
dustc --amd templates/*.dust              # For RequireJS
379
dustc templates/*.dust                    # For direct browser loading
380

381
# Issue: File watching not working
382
# Solution: Use glob patterns and check file permissions
383
dustc --watch "templates/**/*.dust"       # Quote glob patterns
384
```
385

386
## Advanced Usage
387

388
### Custom Build Scripts
389

390
Creating custom build scripts that use `dustc`.
391

392
```javascript
393
#!/usr/bin/env node
394

395
const { exec } = require('child_process');
396
const fs = require('fs');
397
const path = require('path');
398

399
// Custom build script using dustc
400
function buildTemplates() {
401
  const templateDir = 'src/templates';
402
  const outputDir = 'dist/templates';
403

404
  // Ensure output directory exists
405
  if (!fs.existsSync(outputDir)) {
406
    fs.mkdirSync(outputDir, { recursive: true });
407
  }
408

409
  // Compile templates
410
  const command = `dustc --cjs --split ${templateDir}/**/*.dust`;
411

412
  exec(command, (error, stdout, stderr) => {
413
    if (error) {
414
      console.error('Template compilation failed:', error);
415
      process.exit(1);
416
    }
417

418
    console.log('Templates compiled successfully');
419
    console.log(stdout);
420
  });
421
}
422

423
buildTemplates();
424
```
425

426
### Template Preprocessing
427

428
Using `dustc` with template preprocessing pipelines.
429

430
```bash
431
# Preprocess templates before compilation
432
for file in templates/*.dust; do
433
  # Apply preprocessing (example: variable substitution)
434
  sed 's/{{VERSION}}/'$VERSION'/g' "$file" > "processed/$(basename $file)"
435
done
436

437
# Compile processed templates
438
dustc --split processed/*.dust
439

440
# Clean up
441
rm -rf processed/
442
```
443

444
### Performance Optimization
445

446
Optimizing `dustc` usage for large projects.
447

448
```bash
449
# Parallel compilation for large projects
450
find templates -name "*.dust" -print0 | xargs -0 -n 10 -P 4 dustc --split
451

452
# Incremental compilation (only changed files)
453
find templates -name "*.dust" -newer dist/templates.json -exec dustc --split {} +
454

455
# Memory optimization for large template sets
456
NODE_OPTIONS="--max-old-space-size=4096" dustc templates/**/*.dust
457
```