Shopify Liquid templates for modern Swift. One library, one CLI, no package dependencies.
Render HTML, email, Markdown and configuration files with typed values, reusable parsed templates and Swift 6 concurrency. Supply partials and application filters explicitly, inspect templates before rendering, and opt into timing and budget metrics when you need them. Each operation owns its mutable state.
Maintained by Thorsten Fuchs. Select a version
from the published releases.
The 2.0.0 release notes describe the major
version's compatibility changes. main and the documentation site track ongoing
development. Release assets include source, compiled DocC, qualification evidence
and SHA-256 checksums for the exact version.
- A focused language target. Shopify's open-source Liquid core, with standard tags, filters, parser modes and explicit error recovery.
- Parse once, share safely. Engines, templates, inputs and results have checked
Sendableconformance. Variables, counters, diagnostics and budgets belong to one invocation. - Explicit composition. Pass partials by name and configure typed custom filters on an immutable engine. The library performs no implicit file or network I/O.
- Useful inspection. Analyze the actual AST, then inspect an explicit partial bundle for literal dependencies, missing references, dynamic includes and cycles.
- Finite, observable work. Cumulative quotas and cooperative cancellation are part of the operation contract. Metrics are opt-in.
- Evidence you can inspect. Pinned independent fixtures, comparisons with Ruby Liquid, public consumers, Swift Testing, sanitizers and retained release measurements.
| Requirement | Baseline |
|---|---|
| Swift tools and compiler | 6.4 or later |
| Swift language mode | 6 |
| Declared Apple minimums | macOS 14, iOS 17, tvOS 17, watchOS 10, visionOS 1 |
| Runtime qualification | macOS 27 with Swift 6.4; four simulator SDK compilation gates |
| Package products | Liquid library and liquid executable |
| Root package dependencies | None; Foundation comes from the platform SDK |
| License | Apache-2.0 original code, with retained upstream notices |
Simulator compilation is separate from device execution. Linux, WASI and browser
hosting have no runtime qualification claim. The standalone schema qualification
tool uses Swift-JSON; applications linking
Liquid acquire no package dependencies.
After 2.0.0 is published, add the package to Package.swift:
.package(url: "https://github.com/ThorFuchs/Swift-Liquid.git", from: "2.0.0")Then add the library product to your target:
.product(name: "Liquid", package: "swift-liquid")For clean CLI checkout instructions, published-URL qualification and index status, see package discovery.
See the complete public consumer package. The executable examples below are also compiled and run in CI.
import Liquid
let engine = LiquidEngine()
let output = try await engine.render(
template: "Hello, {{ name | upcase }}!",
context: ["name": "Swift"]
)
print(output) // Hello, SWIFT!Context values use Swift literals: strings, integers, finite floating-point
numbers, booleans, arrays, objects and nil. Only nil and false are falsy;
zero, empty strings and empty arrays are truthy. Object literals retain insertion
order and the exact Unicode scalar spelling of keys.
import Foundation
import Liquid
let engine = LiquidEngine()
let template = try LiquidTemplate("{% for item in items %}{{ item }} {% endfor %}")
let output = try await engine.render(template, context: ["items": ["one", "two"]])
print(output.trimmingCharacters(in: .whitespaces)) // one twoKeep parsed templates in your application and share them across tasks. Each render gets independent state. There is no implicit global cache or mutable registry. See limits and concurrency.
import Liquid
let output = try await LiquidEngine().render(
template: "{% render 'card', title: title %}",
context: ["title": "Swift & Liquid"],
templates: ["card": "<h2>{{ title | escape }}</h2>"]
)
print(output) // <h2>Swift & Liquid</h2>render sees the original host inputs and explicit bindings while isolating caller
assignments, loop locals and counters. include follows Liquid's shared-scope behavior.
With templates:, a dynamic include name is evaluated before partial lookup.
The optional byte-exact registry retains its documented selection policy.
Supply partials as sources or parsed templates. HTML escaping is explicit: use
escape or escape_once when inserting text into HTML. Read the
rendering and partials guide.
import Liquid
let value = try LiquidValue(json: #"{"name":"Ada"}"#)
if case .object(let context) = value {
let engine = try LiquidEngine(filters: [
LiquidFilter("greet") { value, _, _ in
guard case .string(let name) = value else {
throw LiquidFilterFailure("Expected a name")
}
return .string("Hello, " + name)
}
])
print(try await engine.render(template: "{{ name | greet | escape }}", context: context)) // Hello, Ada
}The input JSON bridge rejects malformed input, duplicate keys, trailing data and
non-finite numbers. It uses Int and finite Double; supply strings for decimal
data that must remain exact. Custom filters receive typed values and belong to
one engine. Standard filters are protected. See values and JSON
and the custom-filter contract.
import Liquid
let engine = LiquidEngine()
let summary = try engine.inspect(template: "{{ user[key] | escape }}{% render 'card' %}")
print(summary.variableRoots.joined(separator: ",")) // key,user
let graph = try engine.inspectDependencies(
template: "{% include 'card' %}",
templates: ["card": "{% include 'badge' %}"]
)
print(graph.nodes.count) // 2
print(graph.missingReferences.map(\.requestedName).joined(separator: ",")) // badgeInspection traverses the AST without evaluating expressions, calling filters or loading files. Reads include local variables and retained branches; they do not constitute a required-input schema. Dependency inspection admits the whole supplied bundle under explicit bounds and follows the renderer's name lookup rules. Missing references and cycles are findings; they do not prove render failure or success. Read the inspection and dependency contracts.
import Liquid
let measured = try await LiquidEngine().renderWithMetrics(
template: "Hello, {{ name }}!", context: ["name": "Swift"]
)
print(measured.output) // Hello, Swift!
print(measured.metrics.outputBytes) // 13Metrics report monotonic elapsed durations and charged operation counts. Parsed calls omit parse duration. Ordinary rendering collects no timing; the measured APIs share its execution and error behavior. Logical quotas are not process-memory or wall-clock guarantees. See metrics and errors and recovery.
swift run -c release liquid render greeting.liquid --data context.json
swift run -c release liquid render page.liquid --data context.json --partials ./partials --output page.html
swift run -c release liquid validate page.liquid
swift run -c release liquid analyze page.liquid --format json
swift run -c release liquid analyze page.liquid --dependencies --partials ./partials --format jsonThe CLI writes rendered bytes to stdout or the requested file, diagnostics to
stderr, and a nonzero exit status on operational failure. --metrics PATH writes
an independent JSON metrics file. See CLI usage and schemas.
The peer API crosswalk maps common tasks from Ruby Liquid, LiquidJS, Python Liquid, Rust Liquid and Fluid. It explains partial maps, typed inputs, async rendering, recovery and extension boundaries, with pinned sources and explicit evidence grades.
The language authority is Shopify's Liquid reference implementation
and its core language documentation.
Swift-Liquid targets that open-source core. The new LQ1 independent liquid-spec
track retains the unmodified suite verdicts and reference evidence.
The opt-in reviewed profile reports unexpected failures separately from five
documented reference conflicts.
On the recorded 57583aa source snapshot, 4,682 cases matched, five mismatched
for both Swift-Liquid and the pinned Ruby reference, and 425 were not executed.
This is a scoped result, not complete Shopify conformance; the audit
describes the reference conflicts and each unexecuted case.
Storefront objects, theme-only tags,
inheritance, macros, platform data loaders, document rendering and hosting services
remain outside this package's language contract.
The local conformance console runs the
unmodified pinned JSON-RPC track and retains original case verdicts. The separate
liquid-spec-reviewed lane runs the same
track before producing a source-bound reviewed result and exclusion inventory.
The independent Golden Liquid test suite, maintained by James Prior, contributes all 1,098 cases from a pinned revision. The complete fixture bytes, original license, checksum and parser-mode metadata are retained. This corpus is separate from Shopify's own upstream tests.
Release qualification also compares authored probes and date grammar behavior with pinned Ruby Liquid. Receipts distinguish successful renders, parsed cases, expected and recovered errors, supported-year boundaries and reference failures. Swift Testing exercises public contracts, quotas, cancellation, concurrent reuse and graph relationships; independent consumers and CLI/schema checks cover package integration. AddressSanitizer and ThreadSanitizer qualify separate safety concerns. Test counts alone do not establish complete conformance. See the conformance record and pins.
python3 -B Scripts/ci.py --lane native
python3 -B Scripts/ci.py --lane safety
python3 -B Scripts/ci.py --lane docsPerformance evidence retains workloads, sample distributions, checksums, compiler and source identity. Review methodology, variance and cancellation observations and the released qualification archives. No inherited speedup, zero-overhead or process-memory claim is made.
Current independent development evidence retains known mismatches and operational limits. See the source-bound conformance record and development operating policy. A passing correctness workflow does not establish complete conformance or release readiness.
- Documentation site, API reference and guide index
- Contributing, community standards, support and private security reporting
- Contribution isolation and package discovery
- Adversarial testing and structured evidence
- Architecture and provenance, documentation tooling and quality sprints
- Changelog, release process and adopted feature roadmaps
Original Swift-Liquid contributions are Apache-2.0. The engine is adapted from RhoeLiquid; upstream Apache notices are preserved. Golden Liquid fixtures retain their MIT license, and Ruby Date/Time adaptations retain the applicable BSD terms. See NOTICE, third-party notices and the extraction manifest.