|
| 1 | +# Herb Rewriter |
| 2 | + |
| 3 | +**Package:** [`@herb-tools/rewriter`](https://www.npmjs.com/package/@herb-tools/rewriter) |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +Rewriter system for transforming HTML+ERB AST nodes and formatted strings. Provides base classes and utilities for creating custom rewriters that can modify templates. |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +The rewriter package provides a plugin architecture for transforming HTML+ERB templates. Rewriters can be used to transform templates before formatting, implement linter autofixes, or perform any custom AST or string transformations. |
| 12 | + |
| 13 | +### Rewriter Types |
| 14 | + |
| 15 | +- **`ASTRewriter`**: Transform the parsed AST (e.g., sorting Tailwind classes, restructuring HTML) |
| 16 | +- **`StringRewriter`**: Transform formatted strings (e.g., adding trailing newlines, normalizing whitespace) |
| 17 | + |
| 18 | +## Installation |
| 19 | + |
| 20 | +:::code-group |
| 21 | + |
| 22 | +```shell [npm] |
| 23 | +npm add @herb-tools/rewriter |
| 24 | +``` |
| 25 | + |
| 26 | +```shell [pnpm] |
| 27 | +pnpm add @herb-tools/rewriter |
| 28 | +``` |
| 29 | + |
| 30 | +```shell [yarn] |
| 31 | +yarn add @herb-tools/rewriter |
| 32 | +``` |
| 33 | + |
| 34 | +```shell [bun] |
| 35 | +bun add @herb-tools/rewriter |
| 36 | +``` |
| 37 | + |
| 38 | +::: |
| 39 | + |
| 40 | +## Built-in Rewriters |
| 41 | + |
| 42 | +### Tailwind Class Sorter |
| 43 | + |
| 44 | +Automatically sorts Tailwind CSS classes in `class` attributes according to Tailwind's recommended order. |
| 45 | + |
| 46 | +**Usage:** |
| 47 | +```typescript |
| 48 | +import { TailwindClassSorterRewriter } from "@herb-tools/rewriter" |
| 49 | + |
| 50 | +const rewriter = new TailwindClassSorterRewriter() |
| 51 | +await rewriter.initialize({ baseDir: process.cwd() }) |
| 52 | + |
| 53 | +const result = rewriter.rewrite(parseResult, { baseDir: process.cwd() }) |
| 54 | +``` |
| 55 | + |
| 56 | +**Features:** |
| 57 | +- Sorts classes in `class` attributes |
| 58 | +- Auto-discovers Tailwind configuration from your project |
| 59 | +- Supports both Tailwind v3 and v4 |
| 60 | + |
| 61 | +**Example transformation:** |
| 62 | + |
| 63 | +```erb |
| 64 | +<!-- Before --> |
| 65 | +<div class="px-4 bg-blue-500 text-white rounded py-2"> |
| 66 | + <span class="font-bold text-lg">Hello</span> |
| 67 | +</div> |
| 68 | +
|
| 69 | +<!-- After --> |
| 70 | +<div class="rounded bg-blue-500 px-4 py-2 text-white"> |
| 71 | + <span class="text-lg font-bold">Hello</span> |
| 72 | +</div> |
| 73 | +``` |
| 74 | + |
| 75 | +## Custom Rewriters |
| 76 | + |
| 77 | +You can create custom rewriters to transform templates in any way you need. |
| 78 | + |
| 79 | +### Creating an ASTRewriter |
| 80 | + |
| 81 | +ASTRewriters receive and modify the parsed AST: |
| 82 | + |
| 83 | +```javascript [.herb/rewriters/my-rewriter.mjs] |
| 84 | +import { ASTRewriter, asMutable } from "@herb-tools/rewriter" |
| 85 | + |
| 86 | +export default class MyASTRewriter extends ASTRewriter { |
| 87 | + get name() { |
| 88 | + return "my-ast-rewriter" |
| 89 | + } |
| 90 | + |
| 91 | + get description() { |
| 92 | + return "Transforms the AST" |
| 93 | + } |
| 94 | + |
| 95 | + // Optional: Load configuration or setup |
| 96 | + async initialize(context) { |
| 97 | + // context.baseDir - project root directory |
| 98 | + // context.filePath - current file being processed (optional) |
| 99 | + } |
| 100 | + |
| 101 | + // Transform the parsed AST |
| 102 | + rewrite(parseResult, context) { |
| 103 | + if (parseResult.failed) return parseResult |
| 104 | + |
| 105 | + // Access and modify the AST |
| 106 | + // parseResult.value contains the root AST node |
| 107 | + |
| 108 | + // To mutate readonly properties, use asMutable(): |
| 109 | + // const node = asMutable(someNode) |
| 110 | + // node.content = "new value" |
| 111 | + |
| 112 | + return parseResult |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +**Mutating AST Nodes:** |
| 118 | + |
| 119 | +AST nodes have readonly properties. To modify them, use the `asMutable()` helper: |
| 120 | + |
| 121 | +```javascript |
| 122 | +import { asMutable } from "@herb-tools/rewriter" |
| 123 | +import { Visitor } from "@herb-tools/core" |
| 124 | + |
| 125 | +class MyVisitor extends Visitor { |
| 126 | + visitHTMLAttributeNode(node) { |
| 127 | + if (node.value?.children?.[0]?.type === "AST_LITERAL_NODE") { |
| 128 | + const literalNode = asMutable(node.value.children[0]) |
| 129 | + literalNode.content = "modified" |
| 130 | + } |
| 131 | + |
| 132 | + super.visitHTMLAttributeNode(node) |
| 133 | + } |
| 134 | +} |
| 135 | +``` |
| 136 | +
|
| 137 | +### Creating a StringRewriter |
| 138 | +
|
| 139 | +StringRewriters receive and modify strings: |
| 140 | +
|
| 141 | +```javascript [.herb/rewriters/add-newline.mjs] |
| 142 | +import { StringRewriter } from "@herb-tools/rewriter" |
| 143 | + |
| 144 | +export default class AddTrailingNewline extends StringRewriter { |
| 145 | + get name() { |
| 146 | + return "add-trailing-newline" |
| 147 | + } |
| 148 | + |
| 149 | + get description() { |
| 150 | + return "Ensures file ends with a newline" |
| 151 | + } |
| 152 | + |
| 153 | + async initialize(context) { |
| 154 | + // Optional setup |
| 155 | + } |
| 156 | + |
| 157 | + rewrite(content, context) { |
| 158 | + return content.endsWith("\n") ? content : content + "\n" |
| 159 | + } |
| 160 | +} |
| 161 | +``` |
| 162 | +
|
| 163 | +### Using Custom Rewriters |
| 164 | +
|
| 165 | +By default, rewriters are auto-discovered from: `.herb/rewriters/**/*.{js,mjs,cjs}` |
| 166 | +
|
| 167 | +Which means you can just reference and configure them in `.herb.yml` using their filename. |
| 168 | +
|
| 169 | +## API Reference |
| 170 | +
|
| 171 | +### `ASTRewriter` |
| 172 | +
|
| 173 | +Base class for rewriters that transform the parsed AST: |
| 174 | +
|
| 175 | +```typescript |
| 176 | +import { ASTRewriter } from "@herb-tools/rewriter" |
| 177 | +import type { ParseResult, RewriteContext } from "@herb-tools/rewriter" |
| 178 | + |
| 179 | +class MyRewriter extends ASTRewriter { |
| 180 | + abstract get name(): string |
| 181 | + abstract get description(): string |
| 182 | + |
| 183 | + async initialize(context: RewriteContext): Promise<void> { |
| 184 | + // Optional initialization |
| 185 | + } |
| 186 | + |
| 187 | + abstract rewrite(parseResult: ParseResult, context: RewriteContext): ParseResult |
| 188 | +} |
| 189 | +``` |
| 190 | +
|
| 191 | +### `StringRewriter` |
| 192 | +
|
| 193 | +Base class for rewriters that transform strings: |
| 194 | +
|
| 195 | +```typescript |
| 196 | +import { StringRewriter } from "@herb-tools/rewriter" |
| 197 | +import type { RewriteContext } from "@herb-tools/rewriter" |
| 198 | + |
| 199 | +class MyRewriter extends StringRewriter { |
| 200 | + abstract get name(): string |
| 201 | + abstract get description(): string |
| 202 | + |
| 203 | + async initialize(context: RewriteContext): Promise<void> { |
| 204 | + // Optional initialization |
| 205 | + } |
| 206 | + |
| 207 | + abstract rewrite(content: string, context: RewriteContext): string |
| 208 | +} |
| 209 | +``` |
| 210 | +
|
| 211 | +## See Also |
| 212 | +
|
| 213 | +- [Formatter Documentation](/projects/formatter) - Using rewriters with the formatter |
| 214 | +- [Core Documentation](/projects/core) - AST node types and visitor pattern |
| 215 | +- [Config Documentation](/projects/config) - Configuring rewriters in `.herb.yml` |
0 commit comments