liquid-il

LiquidIL is a performance-focused template engine designed for the Shopify Liquid ecosystem, prioritizing execution speed and reduced overhead. By transforming Liquid source code through a multi-stage pipeline—Lexer, Parser, Intermediate Language (IL), Optimizer, and Structured Compiler—it eliminates traditional interpreter loops. Instead of dynamic AST traversal, LiquidIL generates native Ruby procs that leverage YJIT, resulting in machine code execution that effectively removes virtual machine dispatch bottlenecks. It is intended for developers who require high-throughput template rendering in Ruby environments where latency and memory allocations are critical concerns.

• Multi-stage optimization pipeline performing constant folding, dead code elimination, and partial inlining at compile time.

• Direct compilation to native Ruby, avoiding method_missing overhead for standard filters and enabling direct Ruby method calls.

• Advanced caching support using RubyVM Instruction Sequence (ISeq) binaries, allowing for fast serialization and deserialization of compiled templates.

• Flexible execution models including one-shot rendering, pre-parsed template reuse, and standalone Ruby module generation.

• Built-in support for context-aware rendering, file system integration for partial templates, and strict error handling modes.

• Use the CLI for template inspection, IL visualization, and Ruby code generation to profile performance and debug generated logic.

• The engine accepts string inputs as templates and Hash-like objects for variable scoping, maintaining compatibility with standard Liquid variable access patterns.

• When optimizing for performance, use the binary cache (ISeq) to persist templates and bypass parsing steps on production startup.

• The output is typically standard strings or buffers, while inputs consist of source templates and context/assigns dictionaries.

• Be aware that ISeq binaries are platform and Ruby-version specific; ensure deployment environments match compilation targets for optimal compatibility.