Skip to content

Integration Libraries

The following libraries and packages integrate Oicana into different tech stacks. The usual functionality is registration of a template and compilation to different output formats with given inputs. Registering a template runs a warm-up compilation everywhere except in Rust; see required inputs for when that fails.

For all integrations, you can find open source example applications on GitHub.

Typst reports warnings next to errors. For example for an unknown font family that falls back, a deprecated function, or an unused import. A warning does not fail the compilation, so an export succeeds and hands you a document that may not look like you expect. oicana compile prints these warnings; the integrations collect them instead and leave it up to you to look. The browser integration also logs them with console.warn; call setLogLevel('error') to silence that.

Every compiled document carries the warnings of the compilation that produced it, and so does the result of exportOnce. The templates of most integrations also keep the warnings of their most recent compilation. In Go and Ruby, where templates are shared between threads, and in Dart, the template keeps the warnings of the warm-up compilation instead.

IntegrationWarnings on the templateWarnings of a compiled document
Browser / Node.jstemplate.warnings()document.warnings
C#template.Warningsdocument.Warnings
Darttemplate.warnings (warm-up)document.warnings
Gotemplate.Warnings() (warm-up)document.Warnings()
Javatemplate.warnings()document.warnings()
PHP$template->warnings()$document->warnings
Pythontemplate.warningsdocument.warnings
Rubytemplate.warnings (warm-up)document.warnings
Rust–compiled_document.warnings

The warnings are a list of diagnostics, empty when there were none. A diagnostic has these fields, named in the casing of each language:

FieldContent
severitywarning for compilation warnings
messageWhat is wrong, like unknown font family: inter
locationThe file in the template and the 1-based start and end line and column, or nothing if the warning does not point into a file. Files of packages start with the package, like @preview/example:0.1.0/lib.typ. Columns count characters, and the end column is exclusive.
hintsSuggestions on how to fix the problem
traceThe function calls that led to the problem, innermost first, each with a message and an optional location
formattedThe warning rendered for humans with an excerpt of the template, as oicana compile prints it. It carries ANSI color codes if diagnostic coloring is on.

Turning a diagnostic into a string gives you formatted, so it can go straight into a log message:

using document = template.compile(jsonInputs);
for (const warning of document.warnings) {
logger.warn(`Template compiled with a warning: ${warning.formatted}`);
}

Templates that must not fall back to a different font can declare the families they need with [tool.oicana.fonts] require, which turns the warning into an error at registration time.

The export methods cover the common case. Every integration also carries a handful of methods that the getting-started chapters do not use:

APIWhat it does
exportOnce (export_once in Python and Ruby, oicana.ExportOnce in Go)Compile and export a template once without registering it. Nothing is cached and no warm-up compilation runs, which fits stateless and serverless callers. Not available in Rust, where Template::init is cheap enough.
Template.create (Node.js)Register a template on a background thread instead of blocking the event loop. See the Node.js async guide.
manifestThe template’s manifest with its Typst package section and Oicana configuration, including the input definitions.
source / fileRead a text or binary file out of the packed template.
setValidateInputs (set_validate_inputs in Python, validate_inputs= in Ruby)Turn JSON schema validation on or off for one template instance at runtime, overriding the manifest’s validate_json_inputs_by_default.
ZipLimitsRaise the limits used when reading a template archive (10,000 entries and 512 MiB of decompressed content by default). Pass it to the template constructor or exportOnce when oicana pack warns that your template is larger. In Java, the constructor that takes limits also takes the warm-up mode; pass CompilationMode.DEVELOPMENT to keep the default warm-up.
Diagnostic coloringWhether error and warning messages carry ANSI color codes: configureDiagnosticColor (Browser, Node.js), Configuration.ConfigureDiagnosticColor (C#), configureDiagnosticColor (Dart), Configuration.configureDiagnosticColor (Java), oicana.ConfigureDiagnosticColor (Go), Configuration::configureDiagnosticColor (PHP), configure_diagnostic_color (Python), Oicana.configure_diagnostic_color (Ruby), and template.set_diagnostic_color (Rust). Only Rust colors by default.

The integrations support the following platforms:

IntegrationLinux x64Linux arm64Linux musl (Alpine)macOS x64 / arm64Windows x64Windows arm64
Node.js✓✓✓ (x64 and arm64)✓✓✓
Python✓✓✓ (x64 and arm64)✓✓–
C#✓✓✓ (x64 and arm64)✓✓✓
Java✓✓–✓✓–
PHP✓✓–✓✓–
Go✓✓✓ (x64 and arm64)✓✓–
Ruby✓✓✓ (x64 and arm64)✓✓✓
Dart / Flutter✓✓–✓✓✓

The C#, Java, Go, Ruby, and Dart Linux libraries need glibc 2.28 or newer. Dart and Flutter also run on Android, iOS, and the web. The browser integration runs in any browser that supports WebAssembly, and the Rust crate builds for any target Rust and Typst support.

https://www.npmjs.com/package/@oicana/browser

Oicana can run in browsers as WebAssembly. The @oicana/browser npm package contains the .wasm file and a typed interface for it. To not block the UI, it’s advisable to compile templates in a web worker.

An example application using Oicana in a React app can be found on GitHub.

Oicana’s WebAssembly file has to be hosted as part of your frontend application. initialize() loads the file that ships in the package through new URL(..., import.meta.url), which Vite, webpack, Next.js, Parcel, and Rspack resolve on their own. You can also pass the URL of the file to initialize(url). The browser deployment guide covers bundlers that need extra setup.

https://www.nuget.org/packages/Oicana

The nuget package Oicana has a native interface to work with Oicana templates from C#.

Oicana brings the native libraries for every supported platform. For smaller deployments, for example container images, reference Oicana.Core and only the native packages of the platforms you deploy to, like Oicana.Native.linux-musl-x64. The native packages are named after the .NET runtime identifiers: linux-x64, linux-arm64, linux-musl-x64, linux-musl-arm64, osx-x64, osx-arm64, win-x64, and win-arm64.

An example ASP.NET project using the package can be found on GitHub.

https://pub.dev/packages/oicana

The oicana package works in Flutter apps and in plain Dart programs. On Android (arm64, arm, and x64), iOS (devices and simulators), Linux, macOS, and Windows, it calls the native Oicana library, which a build hook downloads for each target and bundles with the app. Methods without the Sync suffix run on a separate isolate there. On the web, the package runs the WebAssembly build of Oicana on the UI thread; Flutter web apps bundle it on their own. Deploy Dart programs with dart build cli, since dart compile exe does not support packages with build hooks. The Dart / Flutter getting-started chapter shows the setup.

An example Flutter app using the package can be found on GitHub, as well as an example Dart service using shelf.

https://github.com/oicana/oicana/tree/main/integrations/go

The Go module go.oicana.com/oicana links the native Oicana library statically through cgo, so builds need a C toolchain. go run go.oicana.com/oicana/cmd/oicana-install downloads the library for your platform, verifies it, and prints the CGO_LDFLAGS that link it. The Go getting-started chapter shows the setup.

An example net/http service using the module can be found on GitHub.

https://central.sonatype.com/artifact/com.oicana/oicana

The com.oicana:oicana Maven package provides a native JNI interface to work with Oicana templates from Java. It uses native bindings for optimal performance on the server.

In addition to the main package, you need to add the native dependency for your target platform(s):

PlatformArtifact
Linux x86_64com.oicana:oicana-linux-x86_64
Linux aarch64com.oicana:oicana-linux-aarch64
macOS x86_64com.oicana:oicana-macos-x86_64
macOS aarch64com.oicana:oicana-macos-aarch64
Windows x86_64com.oicana:oicana-windows-x86_64

For example, in Gradle for Linux x86_64:

dependencies {
implementation("com.oicana:oicana:0.10.0")
runtimeOnly("com.oicana:oicana-linux-x86_64:0.10.0")
}

You can add multiple native dependencies if your team uses different platforms. Only the matching native library will be loaded at runtime.

An example Spring Boot application using the package can be found on GitHub.

https://www.npmjs.com/package/@oicana/node

The npm package @oicana/node provides a native Node.js interface to work with Oicana templates. It uses native bindings for optimal performance on the server.

The package is ESM-only and requires Node.js 20.19+ or 22.12+. CommonJS projects can still load it through require(esm).

An example NestJS application using the package can be found on GitHub.

https://rubygems.org/gems/oicana

The oicana gem provides native bindings to work with Oicana templates from Ruby. Platform gems bring the native library, and native calls release the GVL so other threads keep running. Oicana cannot compile in a process forked after its parent compiled, so with forking servers like Puma in cluster mode, create templates on first use instead of at boot.

An example Rails application using the gem can be found on GitHub.

https://crates.io/crates/oicana

The oicana crate allows you to compile Oicana templates directly in Rust projects. This integration provides the most direct access to Oicana’s core functionality.

An example Axum application using this crate can be found on GitHub.

https://pypi.org/project/oicana/

The oicana Python package provides native bindings to work with Oicana templates from Python. It uses native extensions for optimal performance.

An example FastAPI application using the package can be found on GitHub.

The oicana/oicana Composer package provides a native PHP extension to work with Oicana templates. It uses native bindings for optimal performance.

The package is not on Packagist. It is served from Oicana’s own Composer repository at https://composer.oicana.com, which you register once in your project. The PHP getting-started chapter shows how.

An example PHP Slim application using the package can be found on GitHub.