Image server for TRMNL built with Node.js, JSX and CSS

Design custom layout, content, retrieve secure data and generate image for your TRMNL screen. You can use it via Redirect or Alias plugins, or run it as own BYOS.

Goal: simple and easy to customize starter for people who are already familiar with the JavaScript and CSS ecosystem.

Quick Start

1. Press button Use this template on Github, or clone this repository
2. Copy .env.local to .env.example and change values to yours
3. Run npm run watch for local preview

Or run via Docker:

docker build -t trmnl . && docker run --env-file .env.local -p 3000:3000 trmnl

After run, you can change App.tsx and PrepareData.ts to something that you want to display.

Later, to display screen on device you would need to deploy, provide endpoints in plugin settings, or setup your device to BYOS.

---

Technologies used:

• Satori for rendering JSX to SVG
• resvg-js for rendering SVG to PNG
• Express.js as API server
• TSX for supporting JSX/TSX files

Endpoints for plugins

Image https://yourserver.com/image?secret_key=...
↑ can be used for preview and Alias plugin

JSON https://yourserver.com/plugin/redirect?secret_key=...
↑ can be used for Redirect plugin

JSX components

You can use regular JSX components (similar to React), but without hooks, as screen is rendering only once.
Starting point is App.tsx
It's easier to collect all variables and data in one place, before components. But you can change to any structure that you prefer.

Layout design limitations

• Satori supports CSS Flexbox layout engine only
• it’s not a complete CSS standards implementation
• Each element (like <div>) with a few child nodes should have explicit "display: flex"

Using fonts

To render screen you have to provide a font file. One is attached by default.

Including images

You can include local images by using LocalImage component or specify public url to somewhere.

Your Server

To run your TRMNL server you need any form of server (VM, droplet, pod, instance) somewhere, for example AWS, Google Cloud, Digital Ocean.

• it can be run via Dockerfile or command npm run start
• Better to pass ENV parameters from secure storage that your cloud provider has

Bring your own server (BYOS)

You can skip using plugins and connect your device to your server directly by using BYOS mode. After changing configuration to BYOS your device will stop doing API requests to usetrmnl.com servers. You can even close it in private network for data security.

This repo implements basic BYOS server for one device.

You can enable it with those steps:

1. Put your device's MAC value to ENV key BYOS_DEVICE_MAC (it can be via .env.local). If you don't know it - you can do this step later.
2. Hold round button on your device for more than 5 seconds - you should see connection instructions on screen.
3. Connect your phone to wifi called TRMNL
4. On setup choose Custom server (see screenshot below) and provide address of your server

Troubleshooting:

• To find out MAC address for step 1 you can check logs of server: it will be attempts to connect
• If you see error wrong access-token value from device - you may need to click button Soft reset on device setup stage

---

Goal of this repo: simple and easy to customize.