Twix 🌱🍫

An opinionated formatter for Twig templating engine. Entirely coded with Claude.

Installation

npm install --save-dev @upstatement/twix

Or download the binary directly from GitHub Releases.

Usage

# Format a file (in-place)
twix path/to/file.twig

# Format multiple files
twix "src/**/*.twig"

# Check if files are formatted (exit 1 if not)
twix --check path/to/file.twig

# Format from stdin
cat file.twig | twix --stdin

Configuration

Create a .twixrc.json or twix.config.json file in your project root:

{
  "indentSize": 2,
  "indentStyle": "space",
  "printWidth": 80,
  "customTags": {
    "block": ["if"],
    "inline": ["set"],
    "intermediate": ["else"]
  }
}

Options

| Option | Type | Default | Description | | ------------------------- | -------- | --------- | ------------------------------------------------------------------------- | | indentSize | number | 2 | Number of spaces or tabs per indentation level | | indentStyle | string | "space" | Use "space" or "tab" for indentation | | printWidth | number | 80 | Maximum line width before wrapping attributes | | customTags.block | string[] | [] | Custom Twig block tags (tags with bodies, e.g., {% if %}...{% endif %}) | | customTags.inline | string[] | [] | Custom Twig inline tags (self-closing, e.g., {% set = ... %}) | | customTags.intermediate | string[] | [] | Custom intermediate tags (like {% else %} or {% case %}) |

Built-in Tag Support

Block tags (have a body and {% end* %} tag):

• Standard Twig: if, for, block, set, apply, autoescape, embed, filter, macro, sandbox, verbatim, with
• Craft CMS: switch, cache, js, css, nav, paginate, tag

Inline tags (self-closing):

• Standard Twig: extends, include, use, import, from, do, flush, deprecated
• Craft CMS: exit, header, redirect, requireLogin, requireAdmin, requireGuest, requirePermission

Intermediate tags (appear within blocks):

• else, elseif, case, default

Features

HTML Formatting

• Proper indentation of nested elements
• Block elements (div, p, section, etc.) get their own lines
• Inline elements (span, a, strong, etc.) stay on the same line when possible
• Void elements (meta, link, input, etc.) are self-closing
• Multi-line attribute formatting when attributes exceed printWidth

Twig Formatting

• Block tags are indented with their content
• Expressions ({{ }}) preserve their content
• Whitespace control modifiers ({%- -%}, {{- -}}) are preserved
• Comments ({# #}) are preserved

Twig Inside HTML Attributes

Twix properly handles Twig embedded in HTML attribute values:

<!-- Expressions in attributes -->
<div class="container {{ dynamicClass }}">

<!-- Conditional classes -->
<div class="item {% if active %}is-active{% endif %}">

<!-- Conditional attributes -->
<button {% if disabled %}disabled{% endif %}>

Ignore Blocks

Skip formatting for specific sections using ignore directives:

{# twix:ignore-start #}
<div   class="preserve"   data-value="exactly as-is"  >
  This content will not be formatted
</div>
{# twix:ignore-end #}

Blank Line Handling

• Multiple consecutive blank lines are collapsed to a single blank line
• Blank lines immediately after opening block tags ({% if %}, {% for %}, etc.) are removed
• Intentional blank lines between statements are preserved

Limitations & Known Issues

Not Supported

• Twig expressions are not parsed - Content inside {{ }} and {% %} is preserved as-is, not reformatted
• No HTML entity handling - Entities like   are passed through unchanged
• No CSS/JS formatting - Content inside <style> and <script> tags is not formatted
• Windows line endings - Output uses Unix line endings (\n)

Editor Integration

Pre-commit Hook

Using husky and lint-staged:

// package.json
{
  "lint-staged": {
    "*.twig": "twix"
  }
}

Development

# Build
go build

# Run tests
go test ./...

# Build for all platforms
./scripts/build.sh 0.1.0

License

MIT