pug-tail

library0.1.0-alpha.6jsnpmunverified

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.

web-framework serialization devops

npm install pug-tail

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PUG-TAIL

pug-tail

web-frameworkjavascriptv0.1.0-alpha.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

extend

✓ import { extend } from 'pug-tail'

✗ import extend from 'pug-tail'

Default export does not exist; the function is a named export.

compile

✓ import { compile } from 'pug-tail'

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

No namespace import needed; named import is idiomatic.

extend

✓ const { extend } = require('pug-tail')

✗ const extend = require('pug-tail')

CommonJS requires destructured assignment; default require returns empty object.

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))

pug-tail --version

Debug

Known issues

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

fix

Pin exact version and test upgrades thoroughly.

affects: >=0.1.0-alpha.0

gotchaThe `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);

affects: >=0.1.0-alpha.0

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

fix

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

affects: >=0.1.0-alpha.5

gotchaSlot 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.

affects: >=0.1.0-alpha.0

breakingNode.js 16 support was dropped after v0.1.0-alpha.3.

fix

Use Node >=18.

affects: >=0.1.0-alpha.4

Errors

Common errors & fixes

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

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: No slot named 'default' in component X

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.

SyntaxError: Unexpected token (in JSON output)

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

fix

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

Upgrade

Version history

0.1.0-alpha.6latest on npm

Audit

Dependencies

pug-lexerrequiredTokenizes Pug source input

pug-parserrequiredParses tokens into Pug AST

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/megurock/pug-tail ↗

packagehttps://www.npmjs.com/package/pug-tail ↗

homepagehttps://pug-tail.pages.dev ↗