Why does UniHTML need a server?

Because a browser does the rendering, and a browser is not something you can link into a Go binary.

Converting real-world HTML means implementing CSS: the cascade, flexbox, grid, web fonts, floats, @media print, and whatever a charting library does to a <canvas>. Chrome already does all of that correctly. UniHTML uses it rather than reimplementing a subset, which is why a page that looks right in your browser converts to a PDF that looks the same.

Chrome runs in a container. The UniHTML server is the HTTP service in front of it that takes your request, stages the content, drives the browser through the DevTools protocol, and returns the PDF.

What each part does

Your program only ever talks to the client. unihtml.Connect health-checks the server at startup, so a missing server is an error you get immediately rather than on the first conversion:

if err := unihtml.Connect("localhost:8080"); err != nil {
    return err
}

Check that error. A failed Connect still installs the client, pointed at an address that does not work, so ignoring it turns one clear startup failure into a conversion failure on every request.

The trade

You get browser-grade CSS and JavaScript. You take on running a container, which is a deployment step the other UniDoc libraries do not have. There is no in-process fallback and no pure-Go renderer to switch to.

If that container is unacceptable for your deployment, UniHTML is the wrong tool. Build the document with UniPDF’s creator package instead, which is pure Go and needs nothing running. You give up HTML as the input format and describe the layout in Go, or in a UniPDF template.

Running it

One command, with your metered key:

docker run -d --name unihtml -p 8080:8080 \
  -e UNIDOC_METERED_API_KEY=$UNIDOC_LICENSE_API_KEY \
  unidoccloud/unihtml

The image has Chrome inside it, so there is nothing else to install. The server keeps no database and stores nothing permanently: uploads expire after three minutes.

See the getting started guide for the full setup, and how do I run the UniHTML server in production? for what changes when it is not on your laptop.