Struct TypstEngine 

pub struct TypstEngine<T = TypstTemplateCollection> { /* private fields */ }

Main entry point for compiling Typst documents.

Use TypstEngine::builder() to construct an instance. You can optionally set a main file with main_file(), which allows compiling without specifying the file ID each time.

Examples

With main file (compile without file ID):

static TEMPLATE: &str = "Hello World!";
static FONT: &[u8] = include_bytes!("../examples/fonts/texgyrecursor-regular.otf");

let engine = TypstEngine::builder()
    .main_file(TEMPLATE)
    .fonts([FONT])
    .build();

// Compile the main file directly
let doc: PagedDocument = engine.compile().output.expect("Compilation failed");

Without main file (must provide file ID):

static TEMPLATE: &str = "Hello World!";
static FONT: &[u8] = include_bytes!("../examples/fonts/texgyrecursor-regular.otf");

let engine = TypstEngine::builder()
    .fonts([FONT])
    .with_static_source_file_resolver([("template.typ", TEMPLATE)])
    .build();

// Must specify file ID for each compile
let doc: PagedDocument = engine.compile("template.typ").output.expect("Compilation failed");

See also: Examples directory

Implementations

impl TypstEngine<TypstTemplateCollection>

pub fn builder() -> TypstTemplateEngineBuilder

Creates a new builder for configuring a TypstEngine.

Example

static FONT: &[u8] = include_bytes!("../examples/fonts/texgyrecursor-regular.otf");

let engine = TypstEngine::builder()
    .fonts([FONT])
    .build();

impl TypstEngine<TypstTemplateCollection>

pub fn compile_with_input<F, D, Doc>( &self, main_source_id: F, inputs: D, ) -> Warned<Result<Doc, TypstAsLibError>>

where F: IntoFileId, D: Into<Dict>, Doc: Document,

Compiles a Typst document with input data injected as sys.inputs.

The input will be available in Typst scripts via #import sys: inputs.

To change the injection location, use custom_inject_location().

Example

static TEMPLATE: &str = "#import sys: inputs\n#inputs.name";
static FONT: &[u8] = include_bytes!("../examples/fonts/texgyrecursor-regular.otf");

let engine = TypstEngine::builder()
    .fonts([FONT])
    .with_static_source_file_resolver([("main.typ", TEMPLATE)])
    .build();

let mut inputs = Dict::new();
inputs.insert("name".into(), "World".into_value());

let doc: PagedDocument = engine.compile_with_input("main.typ", inputs)
    .output
    .expect("Compilation failed");

See also: resolve_static.rs

pub fn compile<F, Doc>( &self, main_source_id: F, ) -> Warned<Result<Doc, TypstAsLibError>>

where F: IntoFileId, Doc: Document,

Compiles a Typst document without input data.

pub fn world_builder<I>( &self, main_source_id: I, ) -> TypstWorldBuilder<'_, TypstTemplateCollection>

where I: IntoFileId,

Returns a TypstWorldBuilder for constructing a TypstWorld bound to a specific file.

This is an advanced low-level API. The caller is responsible for driving compilation (e.g. via typst::compile) and for managing the comemo cache afterwards. No cache eviction is performed automatically — use with_world if you want eviction handled for you.

Example

let engine = TypstEngine::builder().build();

let world = engine.world_builder("/main.typ")
    .with_inputs(my_inputs)
    .build()?;
let doc = typst::compile(&world).output.expect("Failed");
comemo::evict(30); // caller manages cache eviction

pub fn with_world<F, I, R>( &self, main_source_id: I, f: F, ) -> Result<R, TypstAsLibError>

where I: IntoFileId, F: FnOnce(&TypstWorld<'_>) -> R,

Execute a closure with a TypstWorld for a specific file, optionally injecting custom inputs.

Runs the comemo cache eviction after the closure returns. For full control use world_builder instead.

Example

let engine = TypstEngine::builder().build();

let pdf_bytes = engine.with_world("/main.typ", |world| {
    let doc = typst::compile(world).output.expect("Failed");
    typst_pdf::pdf(&doc, Default::default()).expect("Failed")
}).unwrap();

// With inputs:
let pdf_bytes = engine.with_world("/main.typ", |world| { ... }).unwrap();

impl TypstEngine<TypstTemplateMainFile>

pub fn compile_with_input<D, Doc>( &self, inputs: D, ) -> Warned<Result<Doc, TypstAsLibError>>

where D: Into<Dict>, Doc: Document,

Compiles the main file with input data injected as sys.inputs.

The input will be available in Typst scripts via #import sys: inputs.

To change the injection location, use custom_inject_location().

Example

static TEMPLATE: &str = "#import sys: inputs\nHello #inputs.name!";
static FONT: &[u8] = include_bytes!("../examples/fonts/texgyrecursor-regular.otf");

let engine = TypstEngine::builder()
    .main_file(TEMPLATE)
    .fonts([FONT])
    .build();

let mut inputs = Dict::new();
inputs.insert("name".into(), "World".into_value());

let doc: PagedDocument = engine.compile_with_input(inputs)
    .output
    .expect("Compilation failed");

See also: small_example.rs

pub fn compile<Doc>(&self) -> Warned<Result<Doc, TypstAsLibError>>

where Doc: Document,

Compiles the main file without input data.

pub fn world_builder(&self) -> TypstWorldBuilder<'_, TypstTemplateMainFile>

Returns a TypstWorldBuilder using the engine’s pre-configured main file.

This is an advanced low-level API. The caller is responsible for driving compilation (e.g. via typst::compile) and for managing the comemo cache afterwards. No cache eviction is performed automatically — use with_world if you want eviction handled for you.

Example

let engine = TypstEngine::builder().main_file("= Hello").build();

let world = engine.world_builder()
    .with_inputs(my_inputs)
    .build()?;
let doc = typst::compile(&world).output.expect("Failed");
comemo::evict(30); // caller manages cache eviction

pub fn with_world<F, R>(&self, f: F) -> Result<R, TypstAsLibError>

where F: FnOnce(&TypstWorld<'_>) -> R,

Execute a closure with a TypstWorld using the engine’s pre-configured main file, optionally injecting custom inputs.

Runs the comemo cache eviction after the closure returns. For full control use world_builder instead.

Example

let engine = TypstEngine::builder().main_file("= Hello").build();

let pdf_bytes = engine.with_world(|world| {
    let doc = typst::compile(world).output.expect("Failed");
    typst_pdf::pdf(&doc, Default::default()).expect("Failed")
}).unwrap();