Skip to content

About

Shopify Liquid for Swift 6.4: a dependency-free engine and CLI with typed Sendable values, reusable templates, custom filters, dependency inspection, and opt-in metrics. Apache-2.0.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Swift-Liquid

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.

CI Release License: Apache-2.0

Read the documentation →

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.

Why Swift-Liquid?

  • 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 Sendable conformance. 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.

Requirements and products

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.

Installation

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.

Render a template

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.

Parse once, render many times

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 two

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

Compose templates explicitly

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 &amp; 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.

Supply JSON and custom filters

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.

Inspect source and partial dependencies

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: ",")) // badge

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

Measure a render

import Liquid

let measured = try await LiquidEngine().renderWithMetrics(
    template: "Hello, {{ name }}!", context: ["name": "Swift"]
)
print(measured.output) // Hello, Swift!
print(measured.metrics.outputBytes) // 13

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

Use the CLI

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 json

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

Coming from another Liquid engine?

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.

Compatibility and independent evidence

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 docs

Performance 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 and community

License and credits

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.

About

Shopify Liquid for Swift 6.4: a dependency-free engine and CLI with typed Sendable values, reusable templates, custom filters, dependency inspection, and opt-in metrics. Apache-2.0.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages