Trait VirtualFileSystem

Source

pub trait VirtualFileSystem: Send + Sync {
    // Required method
    fn read(&self, path: &Path) -> Option<Vec<u8>>;
}

Expand description

Trait for providing virtual files that don’t exist on disk.

This is the primary extension point for batch compilation scenarios. Implement this trait to inject dynamically generated content into Typst’s file system.

§Use Cases

Data injection: Provide /_data/posts.json with blog post metadata
Configuration: Inject site configuration without physical files
Template variables: Provide computed values accessible via json()
Asset manifests: Generate asset URLs at compile time

§Example

use typst_batch::{VirtualFileSystem, set_virtual_fs};
use std::path::Path;

struct MyVirtualFS {
    site_config: String,
}

impl VirtualFileSystem for MyVirtualFS {
    fn read(&self, path: &Path) -> Option<Vec<u8>> {
        match path.to_str()? {
            "/_data/site.json" => Some(self.site_config.as_bytes().to_vec()),
            "/_data/build-time.txt" => {
                Some(chrono::Utc::now().to_rfc3339().into_bytes())
            }
            _ => None, // Fall back to real filesystem
        }
    }
}

set_virtual_fs(MyVirtualFS { site_config: r#"{"title":"My Blog"}"#.into() });

§Thread Safety

Implementations must be Send + Sync as compilation may run in parallel. The provider is called for each file access, so implementations should be efficient (consider caching expensive computations).

§Note on Global State

Due to Typst’s World trait design, the virtual file system must be registered globally via set_virtual_fs. This is a limitation of the underlying architecture, not a design choice.