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.

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

Compilation warnings

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.

Every integration exposes the warnings of the most recent compilation, and every compiled document carries the warnings of the compilation that produced it. When there were none you get the language’s “nothing”: undefined in TypeScript, None in Python, null in C#, Optional.empty() in Java, and None in Rust.

Integration	Warnings of the last compilation
Browser / Node.js	`template.warnings()`
C#	`template.Warnings`
Java	`template.warnings()`
PHP	`$template->warnings()`
Python	`template.warnings`
Rust	`compiled_document.warnings`

const pdf = template.exportPdf(jsonInputs);
const warnings = template.warnings();
if (warnings) {
  logger.warn(`Template compiled with warnings: ${warnings}`);
}

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.

Beyond exporting

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

API	What it does
`exportOnce` (`export_once` in Python)	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.
`inputs`	The template’s input definitions from its manifest, so an application can validate values or build an editor for them. Rust exposes the whole manifest via `manifest()` instead.
`source` / `file`	Read a text or binary file out of the packed template.
`setValidateInputs` (`set_validate_inputs`)	Turn JSON schema validation on or off for one template instance at runtime, overriding the manifest’s `validate_json_inputs_by_default`.
`ZipLimits`	Raise 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 when `oicana pack` warns that your template is larger.
Diagnostic coloring	Whether error and warning messages carry ANSI color codes. See handling errors in Rust, which is the only integration that colors by default.

Browser

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

Oicana can run in browsers as WebAssembly. The @oicana/browser npm package contains a typed interface for interaction with the .wasm file. 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.

Initializing the WASM file

Oicana’s WebAssembly file has to be hosted as part of your frontend application. The initialization method expects the path to the hosted file. If your bundler supports it, the easiest way to get that URL is via import wasmUrl from '@oicana/browser-wasm/oicana_browser_wasm_bg.wasm?url'.

C#

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

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

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

Java

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

Platform	Artifact
Linux x86_64	`com.oicana:oicana-linux-x86_64`
Linux aarch64	`com.oicana:oicana-linux-aarch64`
macOS x86_64	`com.oicana:oicana-macos-x86_64`
macOS aarch64	`com.oicana:oicana-macos-aarch64`
Windows x86_64	`com.oicana:oicana-windows-x86_64`

For example, in Gradle for Linux x86_64:

dependencies {
    implementation("com.oicana:oicana:0.8.0")
    runtimeOnly("com.oicana:oicana-linux-x86_64:0.8.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.

Node.js

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.

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

Rust

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.

Python

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.

PHP

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.