@toppynl/twing

First-class TypeScript and JavaScript Twig template engine.

A fork of nightlycommit/twing extended with Twig 3.x language features and additional extension packages.

Installation

npm install @toppynl/twing

Node.js 16 or later is required.

Basic usage

import { createEnvironment, TwingLoaderArray } from '@toppynl/twing';

const loader = new TwingLoaderArray({
    'index.html': 'Hello {{ name }}!'
});

const env = createEnvironment(loader);

const output = await env.render('index.html', { name: 'World' });
// => 'Hello World!'

Synchronous rendering

import { createSynchronousEnvironment, TwingLoaderArray } from '@toppynl/twing';

const env = createSynchronousEnvironment(loader);

const output = env.renderSync('index.html', { name: 'World' });

Browser / bundle (no filesystem)

import { createEnvironment } from '@toppynl/twing/light';

The light entry point excludes Node.js-only features (convert_encoding, filesystem loader, source maps).

Extension packages

Package	Description
@toppynl/twing-html-extra	html_classes, html_attr, html_attr_merge, html_cva
@toppynl/twing-components	{% props %}, {% component %}, <twig:Name />

import { HtmlExtraExtension } from '@toppynl/twing-html-extra';

const env = createEnvironment(loader, {
    extensions: [new HtmlExtraExtension()]
});

PHP Twig parity

Legend: ✅ Implemented · ❌ Not yet implemented · 📦 Available via extension package

Tags

Tag	Status	PHP Twig	Notes
apply	✅		Apply filters to a block
autoescape	✅		Control auto-escaping
block	✅		Define named template blocks
cache	❌	3.2+	Requires twig/cache-extra
deprecated	✅		Mark template/variable as deprecated
do	✅		Execute expression without output
embed	✅		Include + block override
extends	✅		Template inheritance
filter	✅		Alias for apply
flush	✅		Flush output buffer
for	✅		Loop over sequences
from	✅		Import specific macros
guard	❌	3.15+	Compile-time feature detection
if	✅		Conditional blocks
import	✅		Import macros from template
include	✅		Include a template
macro	✅		Define reusable template functions
sandbox	✅		Sandboxed execution mode
set	✅		Variable assignment
spaceless	✅		Remove whitespace between HTML tags
types	✅	3.13+	Parsed and discarded; no runtime effect
use	✅		Horizontal template reuse
verbatim	✅		Raw output without parsing
with	✅		Scoped variable context
component	📦	—	@toppynl/twing-components
props	📦	—	@toppynl/twing-components

Filters

Filter	Status	PHP Twig	Notes
abs	✅		Absolute value
batch	✅		Split into batches
capitalize	✅		First character uppercase
column	✅		Extract column from array
convert_encoding	✅		lib build only (Node.js)
data_uri	✅		Base64 data URI
date	✅		Format date
date_modify	✅		Modify date
default	✅		Fallback value
escape / e	✅		HTML/JS/CSS/URL escaping
filter	✅		Filter array with arrow function
find	✅	3.11+	First matching element
first	✅		First element
format	✅		sprintf-style formatting
invoke	✅	3.19+	Call arrow function as filter
join	✅		Array to string
json_encode	✅		Encode to JSON
keys	✅		Get array keys
last	✅		Last element
length	✅		Count elements or string length
lower	✅		Lowercase
map	✅		Transform with arrow function
merge	✅		Merge arrays/mappings
nl2br	✅		Newlines to <br>
number_format	✅		Format number
raw	✅		Mark as safe (no escaping)
reduce	✅		Accumulate with arrow function
replace	✅		String replace
reverse	✅		Reverse order
round	✅		Round number
shuffle	✅	3.11+	Randomize array order
slice	✅		Extract portion
slug	✅	3.3+	URL-safe string
sort	✅		Sort (with optional arrow function)
spaceless	✅		Remove whitespace between tags
split	✅		String to array
striptags	✅		Remove HTML tags
title	✅		Title case
trim	✅		Remove whitespace
u	❌		Unicode string operations
upper	✅		Uppercase
url_encode	✅		URL encode
html_attr_merge	📦	—	@toppynl/twing-html-extra
html_attr_type	📦	—	@toppynl/twing-html-extra

Functions

Function	Status	PHP Twig	Notes
attribute	✅		Dynamic attribute access
block	✅		Render named block
constant	✅		Access PHP-style constants
cycle	✅		Cycle through values
date	✅		Create date object
dump	✅		Debug output
enum	❌	3.15+	Access enum cases
enum_cases	❌	3.12+	Iterate all enum cases
include	✅		Include template as function
max	✅		Maximum value
min	✅		Minimum value
parent	✅		Parent block content
random	✅		Random value
range	✅		Number sequence
source	✅		Raw template source
template_from_string	✅		Create template from string
html_attr	📦	—	@toppynl/twing-html-extra
html_classes	📦	—	@toppynl/twing-html-extra
html_cva	📦	—	@toppynl/twing-html-extra
component	📦	—	@toppynl/twing-components

Tests

Test	Status	PHP Twig	Notes
constant	✅		Equals a constant value
defined	✅		Variable is defined
divisible by	✅		Divisible by a number
empty	✅		Is empty
even	✅		Even number
instanceof	✅	3.15+	Instance of a class
iterable	✅		Can iterate
mapping	✅		Is associative array
null / none	✅		Is null
odd	✅		Odd number
same as	✅		Strict equality
sequence	✅		Is indexed array

Operators & language features

Feature	Status	PHP Twig	Notes
and, or, not	✅		Logical operators
b-and, b-or, b-xor	✅		Bitwise operators
xor	✅	3.15+	Logical exclusive OR
==, !=	✅		Loose equality
===, !==	✅	3.23+	Strict equality
<, <=, >, >=	✅		Comparison
<=>	✅		Spaceship (three-way comparison)
in, not in	✅		Containment check
matches	✅		Regex match
starts with, ends with	✅		String prefix/suffix
has some, has every	✅	3.5+	Collection predicates
+, -, *, /, //, %, **	✅		Arithmetic
~	✅		String concatenation
..	✅		Range
??	✅		Null coalescing
?:	✅		Ternary / Elvis
?.	✅	3.23+	Null-safe attribute access
= assignment expression	✅	3.23+	Assign within expression context
=> arrow functions	✅	3.0+	Single-expression lambdas
... spread	✅	3.7+	Spread arrays/mappings
| filter pipe	✅		Filter application
Sequence destructuring	✅	3.23+	{% do [a, b] = arr %}
Object destructuring	✅	3.23+	{% do {name} = obj %}
String interpolation #{}	✅		In double-quoted strings
Whitespace control {%- -%}	✅		Trim surrounding whitespace
Number literals with _	✅	3.17+	1_000_000 readability
Inline expression comments	❌	3.15+	{{ value # comment }}
Enum support	❌	3.12+	enum(), enum_cases()

License

BSD-2-Clause. Based on nightlycommit/twing by Eric MORAND.