trmnlp

A basic self-hosted web server to ease the development and sharing of TRMNL plugins.

Liquid templates are rendered leveraging the TRMNL Design System. They may be generated as HTML (faster, and a good approximation of the final result) or as BMP images (slower, but more accurate).

The server watches the filesystem for changes to the Liquid templates, seamlessly updating the preview without the need to refresh.

Screenshot

Creating a Plugin

This is the structure of a plugin repository.

views/
    full.liquid
    half_horizontal.liquid
    half_vertical.liquid
    quadrant.liquid
config.toml

See config.example.toml for an example config.

The trmnl-hello repository is provided as a jumping-off point for creating new plugins. Simply fork the repo, clone it, and start hacking.

Running the Server (Docker)

docker run \
    -p 4567:4567 \
    -v /path/to/plugin/on/host:/plugin \
    schrockwell/trmnlp

Running the Server (Local Ruby)

Prerequisites:

  • Ruby 3.x
  • For BMP rendering (optional):
    • Firefox
    • ImageMagick

In the plugin repository:

gem install trmnl_preview
trmnlp serve                # Starts the server

Usage Notes

When the strategy is "polling", the specified URL will be fetched once, when the server starts.

When the strategy is "webhook", payloads can be POSTed to the /webhook endpoint. They are saved to tmp/data.json for future renders.

config.toml Reference

  • strategy - Either "polling" or "webhook"
  • url - The URL from which to fetch JSON data (polling strategy only)
  • live_render - Set to false to disable automatic rendering when Liquid templates change (default true)
  • [polling_headers] - A section of headers to append to the HTTP poll request (polling strategy only)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/schrockwell/trmnl_preview.

License

The gem is available as open source under the terms of the MIT License.