Stampdown CLI

Command-line interface for Stampdown template compilation and processing.

Installation

npm install -g @stampdwn/cli

Usage

Basic Commands

# Compile templates to precompiled JavaScript
stampdown compile templates/*.sdt --output dist/

# Process templates with data
stampdown render template.sdt --data data.json

# Watch for changes and recompile
stampdown compile templates/*.sdt --output dist/ --watch

Template Compilation

Compile .sdt (Stampdown Template) files to optimized JavaScript:

# Compile all .sdt files in src/ to dist/
stampdown compile "src/**/*.sdt" --output dist/

# Specify output format
stampdown compile templates/ --output dist/ --format esm
stampdown compile templates/ --output dist/ --format cjs
stampdown compile templates/ --output dist/ --format json

# Enable source maps
stampdown compile templates/ --output dist/ --source-map

# Tree-shake unused helpers
stampdown compile templates/ --output dist/ --known-helpers if,each,with

Template Rendering

Render templates directly from the command line:

# Render with JSON data file
stampdown render template.sdt --data data.json

# Render with inline JSON
stampdown render template.sdt --data '{"name": "World"}'

# Output to file
stampdown render template.sdt --data data.json --output result.html

# Use custom helpers
stampdown render template.sdt --data data.json --helpers ./helpers.js

Batch Processing

Process multiple templates with different data:

# Process all .sdt files with corresponding .json data files
stampdown batch templates/ --data-dir data/ --output dist/

# Example file structure:
# templates/
#   ├── page.sdt
#   ├── email.sdt
# data/
#   ├── page.json
#   ├── email.json

Command Reference

compile

Compile Stampdown templates to JavaScript.

stampdown compile [input] [options]

Arguments:

• input - Input file pattern (glob supported)

Options:

• -o, --output <dir> - Output directory
• -f, --format <format> - Output format: esm, cjs, json (default: esm)
• -k, --known-helpers <list> - Comma-separated list of known helpers for tree-shaking
• -s, --strict - Error on unknown helpers
• -m, --source-map - Generate source maps
• -w, --watch - Watch for changes and recompile
• --template-id <id> - Template identifier for generated code

Examples:

# Basic compilation
stampdown compile "templates/*.sdt" --output dist/

# ESM format with source maps
stampdown compile templates/ -o dist/ -f esm --source-map

# Optimize for known helpers
stampdown compile templates/ -o dist/ -k "if,each,with,uppercase"

# Strict mode (fails on unknown helpers)
stampdown compile templates/ -o dist/ --strict

render

Render templates with data.

stampdown render <template> [options]

Arguments:

• template - Path to template file

Options:

• -d, --data <data> - JSON data (file path or inline JSON)
• -o, --output <file> - Output file (default: stdout)
• -h, --helpers <file> - Custom helpers module
• -p, --partials <dir> - Partials directory
• --plugins <list> - Comma-separated list of plugin names

Examples:

# Render with data file
stampdown render template.sdt --data data.json

# Render with inline data
stampdown render template.sdt -d '{"title": "My Page", "items": [1,2,3]}'

# Use custom helpers
stampdown render template.sdt --data data.json --helpers ./my-helpers.js

# Include partials
stampdown render template.sdt --data data.json --partials ./partials/

batch

Batch process multiple templates.

stampdown batch <templates-dir> [options]

Arguments:

• templates-dir - Directory containing template files

Options:

• -d, --data-dir <dir> - Directory containing JSON data files
• -o, --output <dir> - Output directory
• -h, --helpers <file> - Custom helpers module
• -p, --partials <dir> - Partials directory
• --ext <ext> - Template file extension (default: .sdt)

Configuration File

Create stampdown.config.js for project configuration:

module.exports = {
  input: 'templates/**/*.sdt',
  output: 'dist/',
  format: 'esm',
  knownHelpers: ['if', 'each', 'with', 'unless'],
  strict: false,
  sourceMap: true,
  plugins: ['@stampdwn/llm'],
  helpers: './helpers.js',
  partials: './partials/',
  watch: process.env.NODE_ENV === 'development'
};

Then run:

stampdown compile  # Uses config file automatically

Custom Helpers Module

Create reusable helpers in a separate file:

// helpers.js
module.exports = {
  formatDate: (context, options, date, format = 'YYYY-MM-DD') => {
    // Custom date formatting logic
    return new Date(date).toLocaleDateString();
  },

  calculateTax: (context, options, amount, rate = 0.1) => {
    return (Number(amount) * Number(rate)).toFixed(2);
  }
};

Use with:

stampdown render template.sdt --data data.json --helpers ./helpers.js

Integration Examples

Build Scripts

Add to package.json:

{
  "scripts": {
    "build:templates": "stampdown compile templates/ --output dist/",
    "dev:templates": "stampdown compile templates/ --output dist/ --watch",
    "render:email": "stampdown render email.sdt --data user.json --output email.html"
  }
}

GitHub Actions

name: Build Templates
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g @stampdwn/cli
      - run: stampdown compile templates/ --output dist/
      - uses: actions/upload-artifact@v3
        with:
          name: compiled-templates
          path: dist/

Webpack Integration

// webpack.config.js
const { exec } = require('child_process');

module.exports = {
  // ... other config
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.beforeCompile.tap('StampdownPlugin', () => {
          exec('stampdown compile templates/ --output src/generated/');
        });
      }
    }
  ]
};

Related Packages

• @stampdwn/core - Core templating engine
• @stampdwn/llm - LLM prompt templating plugin

License

MIT