pug-tail

0.1.0-alpha.6 verified Fri May 01 auth: no javascript

A zero-runtime transpiler that expands custom component DSLs with slot syntax directly on the Pug AST. Version 0.1.0-alpha.6 targets Node >=18, ships TypeScript type definitions, and is in early alpha stage. Unlike runtime slot systems (e.g., Vue slots), pug-tail performs static expansion at build time, producing plain Pug output with no client-side overhead. It offers a Vue-like slot syntax (named, scoped, fallback) but compiles away entirely. The project has irregular release cadence and is not yet stable. Key differentiators: no runtime cost, AST-level transformation, and integration with existing Pug toolchains.

Common errors

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause The component definition is missing or malformed in the options object.

fix

Ensure options.components is an object with keys matching component names, each having a template AST node.

error Error: No slot named 'default' in component X ↓

cause Slot reference uses name 'default' but the component defines slots without that name.

fix

Either add a slot named 'default' to the component definition, or rename the slot reference.

error SyntaxError: Unexpected token (in JSON output) ↓

cause The extended AST contains circular references or non-serializable nodes.

fix

Use a custom serializer (e.g., from 'pug-walk') instead of JSON.stringify.

Warnings

breaking API is not stable; alpha versions may introduce breaking changes without deprecation. ↓

fix Pin exact version and test upgrades thoroughly.

gotcha The `extend` function mutates the input AST. Create a deep copy if the original AST is needed later. ↓

fix const copy = JSON.parse(JSON.stringify(ast)); extend(copy, options);

deprecated The `compile` function is deprecated in favor of `extend` and separate post-processing. ↓

fix Replace compile(ast, options) with extend(ast, options) then manually serialize.

gotcha Slot fallback content must be explicitly marked; missing fallback leads to empty output. ↓

fix Ensure every slot in the component definition has a fallback: false or valid AST.

breaking Node.js 16 support was dropped after v0.1.0-alpha.3. ↓

fix Use Node >=18.

Install

npm install pug-tail

yarn add pug-tail

pnpm add pug-tail

Imports

extend
wrong
```
import extend from 'pug-tail'
```
correct
```
import { extend } from 'pug-tail'
```
Default export does not exist; the function is a named export.

compile

wrong

import * as pugTail from 'pug-tail'; pugTail.compile()

correct

import { compile } from 'pug-tail'

No namespace import needed; named import is idiomatic.

extend
wrong
```
const extend = require('pug-tail')
```
correct
```
const { extend } = require('pug-tail')
```
CommonJS requires destructured assignment; default require returns empty object.

Quickstart

Expands a custom component with a slot in Pug AST, converting slot content into component children.

import { extend } from 'pug-tail'\nimport { lex, parse } from 'pug-lexer'\nimport { parse as pugParse } from 'pug-parser'\n\n// Sample Pug template with custom component 'Button' and slot\nconst source = `\nButton\n  slot(name='label')\n    | Click me\n`\n\nconst tokens = lex(source)\nconst ast = pugParse(tokens)\n\n// Define component template for 'Button' (plain Pug AST)\n// In real usage, you'd load from files. For demo, build minimal AST:\nconst buttonTemplate = {\n  type: 'Tag',\n  name: 'button',\n  attrs: { class: 'btn' },\n  children: []\n}\n\nconst extendedAst = extend(ast, {\n  components: {\n    Button: {\n      template: buttonTemplate,\n      slots: { label: true }\n    }\n  }\n})\n\nconsole.log(JSON.stringify(extendedAst, null, 2))