TRMNL Preview Server

Preview third-party TRMNL plugin markup locally before it reaches a device.

The preview server connects to your plugin's plugin_markup_url, validates the response, and renders all four TRMNL layout variants in a desktop workspace. It is intended for plugin authors who already have a local or remote endpoint that returns TRMNL markup JSON.

The tool runs entirely on your machine. It does not upload your markup, credentials, diagnostics, screenshots, or plugin data to any preview service. When you use the default local target mode, requests stay inside your local development environment.

Where This Fits

trmnl-plugin-preview is for Third Party plugins: hosted endpoints that return TRMNL markup in response to a plugin_markup_url request. If you're building a local Liquid-based Private Plugin or Recipe project that lives inside TRMNL, trmnlp is the better fit.

Quick Start

Just want to see it work? Jump to Try It With the Example Plugin for a copy-paste run with no plugin of your own.

Start your plugin server first. Then run the preview server with the markup URL, bearer token, and user UUID you want to test:

npx trmnl-plugin-preview \
  --target http://localhost:8787/trmnl/markup \
  --token local-preview-token \
  --user-uuid local-preview-user

The preview server launches your default browser automatically when it starts. Use --no-open to keep it in terminal-only mode.

Open:

http://127.0.0.1:4568

When you start the server with --target, --token, and --user-uuid, the workspace opens directly after the endpoint diagnostics pass. If you start the server without connection details, the first screen asks for them before the workspace loads.

Develop From Source

git clone https://github.com/danmunoz/trmnl-plugin-preview.git
cd trmnl-plugin-preview
pnpm install
pnpm run install:browsers
pnpm dev

To pass a target while running from source:

pnpm dev -- \
  --target http://localhost:8787/trmnl/markup \
  --token local-preview-token \
  --user-uuid local-preview-user

Try It With the Example Plugin

Don't have a plugin endpoint yet? The repo ships a tiny, zero-dependency example so you can see the preview working in under a minute. It returns markup for all four views, each drawing a few labelled geometric figures — a clean starting point you can copy for your own endpoint.

The example lives in the source tree (it isn't part of the npm package), so use a source checkout — see Develop From Source. Then run the example endpoint and the preview in two separate terminals (each is a long-running server):

# terminal 1 — the example plugin endpoint (http://localhost:8787)
node examples/shapes/server.mjs

# terminal 2 — the preview, pointed at the example
pnpm dev -- \
  --target http://localhost:8787/trmnl/markup \
  --token local-preview-token \
  --user-uuid local-preview-user

Open http://127.0.0.1:4568 and all four layout variants render. The example's defaults (localhost:8787, token local-preview-token, user local-preview-user) already match the preview's defaults, so pnpm dev with no flags works too.

To change what each slot draws, edit examples/shapes/server.mjs — it's a single file with a FIGURES map and one buildView(...) call per view. See examples/shapes/README.md for the walkthrough and the exact markup contract your own endpoint should return.

What You Need

• Node.js >=24 <26
• A TRMNL plugin markup endpoint — or the bundled example to start
• A bearer token accepted by that endpoint
• A user UUID for the preview request
• Chromium for PNG export, installed with npx playwright install chromium

By default, the target URL must be local: localhost, 127.0.0.1, or [::1]. This prevents the preview server from becoming a generic credential relay. To test a remote endpoint that you control, start with --allow-remote-targets. In that mode, the preview server sends your configured bearer token and preview request to the remote URL you provide.

What It Shows

The dashboard renders these four variants at once:

• full
• half horizontal
• half vertical
• quadrant

Controls let you switch between TRMNL OG and TRMNL X, landscape and portrait, the TRMNL framework font modes, and live HTML or rendered PNG previews. Both device models fit into the same 640-pixel preview stage while preserving their native aspect ratios. Rendered HTML and PNG routes use the selected model's physical device dimensions.

Endpoint diagnostics are available from the workspace status control. They show the target host, HTTP status, response keys, and a redacted curl command.

Common Options

trmnl-plugin-preview \
  --port 4568 \
  --target http://localhost:8787/trmnl/markup \
  --token local-preview-token \
  --user-uuid local-preview-user

To open the workspace from another device on your network, bind the server to the exact address of the network interface you want to expose:

trmnl-plugin-preview --host 192.168.1.20 --port 4568 --no-open

Then open http://192.168.1.20:4568 from the other device. Binding an exact interface address limits the listener to that interface and allows PNG rendering to call back into the same listener.

See Configuration for the full CLI and environment variable reference.

Troubleshooting

The workspace does not open
The preview server validates your endpoint first. Check the error shown on the first screen. The most common causes are wrong bearer token, wrong user UUID, invalid JSON, or missing markup fields.

Remote target rejected
Remote targets are disabled by default. Use --allow-remote-targets only for endpoints you control.

PNG previews fail

Install Chromium with:

npx playwright install chromium

Port already in use
Start on another port:

trmnl-plugin-preview --port 4569

Reference

• Endpoint contract
• Configuration
• HTTP routes