Typst Rails
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.
Installation
Add this line to your application's Gemfile:
gem 'typst-rails'And then execute:
$ bundle installOr install it yourself as:
$ gem install typst-railsRails Usage
.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 %>
#let data = json("typst_data.json")
= #data.title
Author: #data.author
Generated on <%= Time.now.strftime("%Y-%m-%d") %>Data reaches the template two ways. ERB runs first, in the view context, so
instance variables and helpers work as in any view; note that <%= %> output
is not escaped. The controller's instance variables and locals are also
serialized to typst_data.json, which Typst reads with json(). That file is
written only when the template source mentions typst_data.json.
The TypstRails::Helpers methods, such as escape_typst and
markdown_to_typst, are available in views:
= <%= escape_typst(@title) %>In views, url_encode remains ActionView's own, which encodes spaces as %20.
Rage Integration
Rage controllers have no template handlers, so when Rage is detected,
RageController::API gains a render_typst helper instead:
class ReportsController < RageController::API
def monthly
@title = "Monthly Report"
render_typst "app/views/reports/monthly.typ", { author: "Durable Systems Inc." }
end
endAs with Sinatra, the template runs through ERB in the controller's scope,
with the locals hash as local variables, and the locals are also written to
typst_data.json. Pass status: to set the response status. If
typst-rails loads before Rage's controllers, add
include TypstRails::RageIntegration::ControllerHelpers to your base
controller.
Sinatra Integration
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."
}
endThe template runs through ERB first, in the route's scope, so instance
variables, helpers such as escape_typst, and the locals hash are all
available. The locals are also written to typst_data.json for templates
that read it.
Configuration
TypstRails.configure do |config|
config.typst_executable_path = "/custom/path/to/typst"
config.default_root_path = Rails.root.join("app", "assets", "typst")
enddefault_root_path sets the Typst root, so templates can load files beneath
it with root-relative paths, such as #image("/images/logo.png"). Each render
creates a short-lived working directory inside the root, so it must be
writable. Without it, each render compiles in a private temporary directory
and cannot read your application's files.
Compilation Backends
TypstRails compiles documents through a pluggable backend. Two backends ship
with the gem:
-
:clishells out to thetypstexecutable. This is the original approach and requires Typst to be installed separately and available onPATH. -
:gemuses thetypstRubyGem, 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
endYou 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 }Testing
The gem includes comprehensive testing at multiple levels:
Unit Tests
Run the unit test suite:
bundle exec rake testTests cover:
- Framework detection (Rails, Rage, Sinatra)
- Core renderer functionality
- Error handling and edge cases
- All helper methods
- Input validation and defensive programming
End-to-End Tests
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_e2eE2E 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.
Docker End-to-End Tests
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:dockerSee e2e-tests/docker/README.md for detailed documentation.
Code Coverage
bundle exec rake test
# Coverage report will be in coverage/index.html
open coverage/index.htmlDevelopment
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.
Contributing
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.
License
The gem is available as open source under the terms of the MIT License.