Installation

HTVG is available in multiple formats to suit your development environment. Choose the installation method that matches your project.

Node.js / WASM
Rust
CLI

JavaScript/TypeScript via npm

Install HTVG as a dependency in your Node.js, browser, or edge runtime project.

npm install htvg

Browser Usage

The WASM module auto-fetches the .wasm file in browser environments:

import { init, compileDocument } from "htvg";

// Initialize once before any compilation
await init();

const result = compileDocument({
  meta: { width: 400 },
  content: {
    type: "text",
    content: "Hello from the browser!",
    style: { fontSize: 24 }
  }
});

console.log(result.svg);

The init() function must be called once before using any compilation functions. In browsers, it automatically fetches the WASM module.

Node.js Usage

For Node.js, you need to explicitly load the WASM file:

import { init, compileDocument } from "htvg";
import fs from "node:fs";

// Load WASM from node_modules
const wasmBuffer = fs.readFileSync(
  "node_modules/htvg/dist/wasm/htvg_bg.wasm"
);
await init(wasmBuffer);

const result = compileDocument({
  meta: { width: 600 },
  content: {
    type: "flex",
    style: { flexDirection: "column", gap: 12 },
    children: [
      { type: "text", content: "Title", style: { fontSize: 20, fontWeight: 700 } }
    ]
  }
});

console.log(result.svg);

Cloudflare Workers

For Cloudflare Workers and other edge runtimes, import the WASM module directly:

import { init, compileDocument } from "htvg";
import wasmModule from "htvg/htvg.wasm";

await init(wasmModule);

export default {
  async fetch(request) {
    const result = compileDocument({
      meta: { width: 800 },
      content: {
        type: "text",
        content: "Generated at the edge!",
        style: { fontSize: 32 }
      }
    });

    return new Response(result.svg, {
      headers: { "Content-Type": "image/svg+xml" }
    });
  }
};

HTVG’s WASM build is optimized for edge runtimes with minimal overhead and fast cold starts.

Rust via Cargo

Add HTVG to your Rust project using Cargo:

cargo add htvg

Or manually add it to your Cargo.toml:

Cargo.toml

[dependencies]
htvg = "*"

Basic Usage

use htvg::{compile, CompileOptions};

fn main() {
    let json = r###"{
        "type": "flex",
        "style": { "width": 400, "padding": 20, "backgroundColor": "#ffffff" },
        "children": [
            {
                "type": "text",
                "content": "Hello World",
                "style": { "fontSize": 24, "color": "#333333" }
            }
        ]
    }"###;

    let options = CompileOptions {
        width: 400.0,
        height: None,  // Auto-computed
        font_size: 16.0,
        font_family: None,
        fonts: Vec::new(),
    };

    let result = compile(json, &options).unwrap();
    println!("{}", result.svg);
}

Using CompileOptions Default

use htvg::{compile, CompileOptions};

let json = r###"{
    "type": "box",
    "style": { "width": 200, "height": 100, "backgroundColor": "#ff0000" }
}"###;

let options = CompileOptions::default();
let result = compile(json, &options).unwrap();

assert!(result.svg.contains("rect"));
assert!(result.svg.contains("#ff0000"));

Compiling Documents

Use the compile_document function for self-contained HTVG documents:

use htvg::compile_document;

let doc_json = r###"{
    "meta": { "width": 800 },
    "content": { 
        "type": "flex", 
        "children": [...] 
    }
}"###;

let result = compile_document(doc_json).unwrap();

Make sure your JSON is valid and follows the HTVG element schema. Invalid JSON or malformed elements will return a CompileError with kind "parse_error".

Building from Source

To build HTVG from source:

Clone the repository

git clone https://github.com/pavi2410/htvg
cd htvg

Check the build

cargo check

Run tests

cargo test

Build release

cargo build --release

Building WASM from Source

To build the WASM package:

wasm-pack build --target web

Command Line Interface

The HTVG CLI allows you to compile JSON files to SVG from the command line.

Installation via Cargo

cargo install htvg-cli

The CLI binary is named htvg and will be available in your PATH after installation.

Usage

Once installed, compile a JSON document to SVG:

htvg input.json -o output.svg

Example Workflow

Create a JSON document

Create a file called hello.json:

hello.json

{
  "meta": {
    "width": 400
  },
  "content": {
    "type": "flex",
    "style": {
      "width": 400,
      "padding": 32,
      "backgroundColor": "#ffffff",
      "flexDirection": "column",
      "gap": 12
    },
    "children": [
      {
        "type": "text",
        "content": "Hello, HTVG!",
        "style": {
          "fontSize": 32,
          "fontWeight": "bold",
          "color": "#1a1a1a"
        }
      }
    ]
  }
}

Compile to SVG

htvg hello.json -o hello.svg

View the output

Open hello.svg in your browser or image viewer to see the result.

Verify Installation

After installation, verify HTVG is working correctly:

import { init, version } from "htvg";

await init();
console.log("HTVG version:", version());

System Requirements

Rust: Rust 1.70 or higher
Node.js: Node.js 18 or higher (for WASM usage)
WASM: WebAssembly support in target environment

Troubleshooting

WASM Module Not Found

If you see “WASM module not found” errors in Node.js:

Ensure you’re passing the WASM buffer to init()
Verify the path to htvg_bg.wasm is correct
Check that the file exists in node_modules/htvg/dist/wasm/

Rust Compilation Errors

If you encounter compilation errors:

Update Rust to the latest stable version: rustup update
Clear the build cache: cargo clean
Rebuild: cargo build

Type Errors in TypeScript

If you see TypeScript errors:

Ensure you have the latest version: npm update htvg
Check that your tsconfig.json includes "module": "ESNext" or "NodeNext"

Next Steps

Quick Start Guide

Now that HTVG is installed, follow our quick start guide to build your first project

Get Started

Core Concepts

Guides

Installation

Installation

JavaScript/TypeScript via npm

Browser Usage

Node.js Usage

Cloudflare Workers

Rust via Cargo

Basic Usage

Using CompileOptions Default

Compiling Documents

Building from Source

Building WASM from Source

Command Line Interface

Installation via Cargo

Usage

Example Workflow

Verify Installation

System Requirements

Troubleshooting

WASM Module Not Found

Rust Compilation Errors

Type Errors in TypeScript

Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation

​JavaScript/TypeScript via npm

​Browser Usage

​Node.js Usage

​Cloudflare Workers

​Rust via Cargo

​Basic Usage

​Using CompileOptions Default

​Compiling Documents

​Building from Source

​Building WASM from Source

​Command Line Interface

​Installation via Cargo

​Usage

​Example Workflow

​Verify Installation

​System Requirements

​Troubleshooting

​WASM Module Not Found

​Rust Compilation Errors

​Type Errors in TypeScript

​Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Installation

JavaScript/TypeScript via npm

Browser Usage

Node.js Usage

Cloudflare Workers

Rust via Cargo

Basic Usage

Using CompileOptions Default

Compiling Documents

Building from Source

Building WASM from Source

Command Line Interface

Installation via Cargo

Usage

Example Workflow

Verify Installation

System Requirements

Troubleshooting

WASM Module Not Found

Rust Compilation Errors

Type Errors in TypeScript

Next Steps