trmnlp Development Tool

A transform script allows you to run code (python, ruby, php, or node) against a polled API response before it reaches your Liquid templates. This matches the hosted plugin service's behavior.

Implementation

1. Create a file at src/transform.{py,rb,php,js}.
2. Define a run(input) function. The function receives the polled response as JSON via stdin and returns the new data object.

Configuration

• Enabled by default: Transforms run automatically if the file exists.
• Disable transforms: Set transform_runtime: disabled in .trmnlp.yml.
• Remote Daemon: To test against a real microVM daemon, set serverless_daemon_url: in .trmnlp.yml and provide the token via the $TRMNL_SERVERLESS_DAEMON_API_KEY environment variable.

Language Detection

The language is determined by the file extension:

• src/transform.py -> python
• src/transform.rb -> ruby
• src/transform.js -> node
• src/transform.php -> php

# src/transform.py
def run(input):
    return {"items": [x["title"] for x in input["data"]]}

# .trmnlp.yml
transform_runtime: enabled
serverless_daemon_url: https://transforms.your-team.example

export TRMNL_SERVERLESS_DAEMON_API_KEY=...
trmnlp serve

If your plugin fetches data from a third-party API requiring authorization, you can run the OAuth2 authorization code flow locally using trmnlp serve. This allows you to preview the plugin with a real token. The token is injected into polling requests exactly as it is in the hosted service.

1. Configure the provider

Add the following keys to src/settings.yml. These settings are synced with the hosted service via trmnlp push and trmnlp pull.

2. Set credentials locally

OAuth app credentials must stay local and should be set as environment variables:

3. Register the redirect URI

In your OAuth provider's dashboard, register the following redirect URI: http://localhost:4567/oauth/callback (Note: match the port if running trmnlp serve on a different port).

4. Connect

Run trmnlp serve and open the preview. If not yet connected, click the Connect account banner to authorize in your browser. Tokens are stored in the local cache directory and refreshed automatically.

# src/settings.yml
oauth_enabled: "true"
oauth_authorize_url: https://github.com/login/oauth/authorize
oauth_token_url: https://github.com/login/oauth/access_token
oauth_scopes: "read:user user:email"
oauth_pkce_enabled: "true"
# oauth_scope_separator: " "
# oauth_refresh_url: https://...

export TRMNL_OAUTH_CLIENT_ID=your-oauth-app-client-id
export TRMNL_OAUTH_CLIENT_SECRET=your-oauth-app-client-secret

http://localhost:4567/oauth/callback

If you prefer not to install Ruby locally, you can run trmnlp using Docker.

Standard execution

Run the server by mounting your current directory to /plugin:

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

Note: --bind 0.0.0.0 is required inside Docker to make the preview reachable from your host browser.

Interactive Mode

To run multiple commands (like login and clone) within a container, start an interactive shell and mount your local config directory to persist your API key:

docker run -it \
    --pull always \
    --publish 4567:4567 \
    --volume "$HOME/.config/trmnlp:/root/.config/trmnlp" \
    --volume "$(pwd):/plugin" \
    --entrypoint /bin/bash \
    trmnl/trmnlp

Docker Compose

For a pre-configured setup, use a docker-compose.yml:

services:
  trmnlp:
    image: trmnl/trmnlp
    pull_policy: always
    command: ["serve"]
    ports:
      - "4567:4567"
    volumes:
      - .:/plugin

trmnlp supports serverless transforms using Python. This allows you to enrich raw polled data (e.g., an array of IDs) with additional data from external APIs before it reaches your Liquid templates.

The Transform Contract

Your Python script must define a run(input) function. This function is the same code shape used in production.

1. Input: The function receives an input dictionary containing the polled data under the input["data"] key.
2. Logic: You can use standard libraries like urllib.request to make additional HTTPS calls to fetch detailed records.
3. Output: The function must return a dictionary containing the cleaned, enriched data structure that your Liquid templates will iterate over.

Configuration

To use a Python transform, ensure your src/settings.yml includes:

• serverless_language: python
• strategy: polling (or your chosen strategy)

To enable running these transforms in-process during local development, your .trmnlp.yml must have:

• transform_runtime: enabled