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 PNG images (slower, but more accurate).

Custom Liquid filters and tags are provided by the trmnl-liquid gem.

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

This is the structure of a plugin project:

.
├── .trmnlp.yml
├── bin
│   └── dev
└── src
    ├── full.liquid
    ├── half_horizontal.liquid
    ├── half_vertical.liquid
    ├── quadrant.liquid
    ├── shared.liquid
    └── settings.yml

You can start building a plugin locally, then push it to the TRMNL server for display on your device.

trmnlp init [my_plugin]  # generate
cd [my_plugin]
trmnlp serve             # develop locally
trmnlp login             # authenticate
trmnlp push              # upload

If you have built a plugin with the web-based editor, you can clone it, work on it locally, and push changes back to the server.

trmnlp login                   # authenticate
trmnlp clone [my_plugin] [id]  # first download
cd [my_plugin]
trmnlp serve                   # develop locally
trmnlp push                    # upload

The trmnlp login command saves your API key to ~/.config/trmnlp/config.yml.

If an environment variable is more convenient (for example in a CI/CD pipeline), you can set $TRMNL_API_KEY instead.

The bin/trmnlp script is provided as a convenience. It will use the local Ruby gem if available, falling back to the trmnl/trmnlp Docker image.

You can modify the bin/trmnlp script to set up environment variables (plugin secrets, etc.) before running the server.

Prerequisites:

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

gem install trmnl_preview
trmnlp serve

docker run \
    --publish 4567:4567 \
    --volume "$(pwd):/plugin" \
    trmnl/trmnlp serve

The .trmnlp.yml file lives in the root of the plugin project, and is for configuring the local dev server.

System environment variables are made available in the {{ env }} Liquid varible in this file only. This can be used to safely supply plugin secrets, like API keys.

All fields are optional.

---
# auto-reload when files change (`watch: false` to disable)
watch:
  - src
  - .trmnlp.yml

# values of custom fields (defined in src/settings.yml)
custom_fields:
  station: "{{ env.ICAO }}" # interpolate $IACO environment variable

# Time zone IANA identifier to inject into trmnl.user; see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
time_zone: America/New_York

# override variables
variables:
  trmnl:
    user:
      name: Peter Quill
    plugin_settings:
      instance_name: Kevin Bacon Facts

The settings.yml file is part of the plugin definition.

See TRMNL documentation for details on this file's contents.

To test, run:

bin/rake

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

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