TypstRails provides helpers for using Typst typesetting system with Ruby applications. Generate high-quality PDFs from Typst templates with seamless framework integration for Rails, Rage, and Sinatra. TypstRails can be used with either the typst gem or with a typst CLI.

Add this line to your application's Gemfile:

gem 'typst-rails'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install typst-rails

.typ templates are automatically registered and work just like ERB templates:

# app/controllers/reports_controller.rb
class ReportsController < ApplicationController
  def monthly
    @title = "Monthly Report"
    @author = "Durable Systems Inc."

    respond_to do |format|
      format.pdf { render template: "reports/monthly" }
    end
  end
end

<%# app/views/reports/monthly.typ %>
<% data = { title: @title, author: @author } %>
#let data = json("typst_data.json")

= #data.title

Author: #data.author

Generated on <%= Time.now.strftime("%Y-%m-%d") %>

Rage support is automatically enabled when the Rage framework is detected. Template integration follows Rage's conventions.

When Sinatra is detected, a typst helper method is available:

require 'sinatra'
require 'typst_rails'

get '/report.pdf' do
  typst 'templates/report.typ', {
    title: "Monthly Report",
    author: "Durable Systems Inc."
  }
end

TypstRails.configure do |config|
  config.typst_executable_path = "/custom/path/to/typst"
  config.default_root_path = Rails.root.join("app", "assets", "typst")
end

TypstRails compiles documents through a pluggable backend. Two backends ship with the gem:

• :cli shells out to the typst executable. This is the original approach and requires Typst to be installed separately and available on PATH.

• :gem uses the typst RubyGem, a native extension that compiles in-process—no subprocess or separate Typst install required. Add it to your Gemfile to enable it:

  gem "typst"

By default (config.backend = :auto), TypstRails prefers the typst gem when it's installed and falls back to the CLI otherwise. Force a specific backend if you need to:

TypstRails.configure do |config|
  config.backend = :gem # or :cli
end

You can also register your own backend—for example, to compile against a remote Typst service:

class MyRemoteBackend < TypstRails::Backends::Base
  def available?
    true
  end

  def compile(typ_path, root_dir)
    # ... return PDF bytes, or raise TypstRails::Error on failure
  end
end

TypstRails::Backends::Registry.register(:my_remote, MyRemoteBackend.new)
TypstRails.configure { |config| config.backend = :my_remote }

The gem includes comprehensive testing at multiple levels:

Run the unit test suite:

bundle exec rake test

Tests cover:

• Framework detection (Rails, Rage, Sinatra)
• Core renderer functionality
• Error handling and edge cases
• All helper methods
• Input validation and defensive programming

Requires Typst to be installed.

The E2E tests process real ERB templates using all helpers and compile them with Typst to generate actual PDFs:

# Run E2E tests
bundle exec rake e2e

# Run all tests (unit + E2E)
bundle exec rake test_all

# Clean up generated test outputs
bundle exec rake clean_e2e

E2E tests verify:

• Text escaping with real Typst special characters
• HTML to Typst conversion with actual compilation
• Markdown to Typst syntax transformation
• External Markdown file inclusion
• Complex real-world templates with multiple helpers

See e2e-tests/README.md for detailed documentation.

Requires Docker.

Verifies backend auto-detection (:cli vs :gem) across isolated container environments, and that the gem works correctly when built and installed like a real release rather than loaded from the working tree:

bundle exec rake e2e:docker

See e2e-tests/docker/README.md for detailed documentation.

bundle exec rake test
# Coverage report will be in coverage/index.html
open coverage/index.html

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests (note: currently, the gem has a basic structure and tests will be expanded with functionality). You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/durable-oss/typst-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.