0.0
The project is in a healthy, maintained state
TypstRails integrates the Typst typesetting system with Ruby applications. Provides automatic framework detection and integration for Rails, Rage, and Sinatra, with full standalone support. Generate high-quality PDFs from Typst templates with built-in helpers for text escaping, HTML/Markdown conversion, and data binding. Developed following the Durable Philosophy emphasizing stability, long-term maintainability, and pragmatic solutions.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

>= 2.0
~> 5.0
~> 2.0
>= 12.0
~> 1.50
~> 0.22

Runtime

 Project Readme

Typst Rails

CI Gem Version License: MIT

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 install

Or install it yourself as:

$ gem install typst-rails

Rails 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
end

As 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."
  }
end

The 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")
end

default_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:

  • :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 }

Testing

The gem includes comprehensive testing at multiple levels:

Unit Tests

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

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

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:docker

See 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.html

Development

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.