Getting Started & Local Development

This guide provides step-by-step instructions to set up and run the TRMNL Salah Prayer Times Plugin project locally for development and testing.

Prerequisites

Before you begin, ensure you have the following installed and configured:

1. Node.js: Version 20.x or later.
2. Yarn: The package manager recommended for this project. Install it globally: npm install -g yarn.
3. Serverless Framework CLI: For deploying and running serverless functions locally. Install it globally: npm install -g serverless.
4. AWS Account: An AWS account with appropriate IAM permissions to deploy Lambda functions and API Gateway endpoints if you plan to deploy to the cloud. For local development with serverless-offline, this is not strictly necessary but required for full deployment.
5. Supabase Account: For database services. The project uses Supabase client v2.49.4.
6. TRMNL Device with Developer Edition add-on: Required for testing the plugin on a physical TRMNL device.

Key Dependencies

The project leverages a robust set of libraries and tools:

• TypeScript: Version 5.8.3 for type-safe development.
• AWS Lambda Powertools: Version 2.18.0 for enhanced observability (logging, tracing, metrics) in Lambda functions.
• date-fns: Version 4.1.0 for comprehensive date and time utilities.
• date-fns-tz: Version 3.2.0 for timezone-aware date operations.
• Supabase JS Client: Version 2.49.4 for interacting with the Supabase database.
• Zod: Version 3.24.2 for robust runtime validation of data schemas.
• Jest: Version 29.7.0 for unit and integration testing.
• ESLint: Version 9 for code linting and style enforcement.
• Husky: Version 9 for Git hooks, ensuring code quality pre-commit/pre-push.

TRMNL Plugin Setup

To integrate the plugin with your TRMNL device, you need to register it in the TRMNL dashboard:

1. Log in to your TRMNL account and navigate to the plugin creation page: https://usetrmnl.com/plugins/my/new↗.

2. Configure the new plugin with the following details. Note that your-api-gateway-url refers to the endpoint URL of your deployed backend (e.g., from yarn serverless:deploy), not your local serverless-offline URL, as physical TRMNL devices cannot access local endpoints directly.

   • Name: Salah Times
   • Description: Islamic prayer times & Hijri date for TRMNL
   • Icon: Upload a 40x40 PNG icon of your choice.
   • Installation URL: https://your-api-gateway-url/install
   • Installation Success Webhook URL: https://your-api-gateway-url/installation-success
   • Plugin Management URL: https://your-api-gateway-url/manage
   • Plugin Markup URL: https://your-api-gateway-url/plugin-markup

Supabase Setup

Supabase is used to store user-specific settings for the plugin.

1. Create a New Project: Go to Supabase↗ and create a new project.
2. Database Schema: Once your project is created, you'll need to set up the user_settings table. Although the schema.sql file is not directly included in the provided content, the user_settings table should be created with the following structure (refer to src/clients/supabase/database.types.ts for a full schema definition if needed):
   • uuid: text (Primary Key), stores the TRMNL user's unique ID.
   • city: text, stores the user's preferred city.
   • country: text, stores the user's preferred country.
   • method: int, stores the prayer calculation method ID.
   • timeformat: text ('12h' or '24h').
   • asr_method: text ('standard' or 'hanafi').
   • maghrib_offset: int, offset for Maghrib prayer in minutes.
   • created_at: timestamp with time zone.
   • updated_at: timestamp with time zone.
   • You'll also need to set up Row Level Security (RLS) policies to allow insert and update for authenticated users or service roles, as appropriate.
3. Obtain Credentials: From your Supabase project settings (under "API"), retrieve your:
   • Project URL (SUPABASE_URL)
   • Service Role Key (SUPABASE_SERVICE_KEY)

Environment Variables

The project requires several environment variables for both TRMNL integration and Supabase connectivity. Create a .env file in the project root or export them in your shell:

• TRMNL_CLIENT_ID and TRMNL_CLIENT_SECRET: Obtain these from your TRMNL plugin settings after creation.
• SUPABASE_URL and SUPABASE_SERVICE_KEY: Obtained from your Supabase project settings.
• IS_OFFLINE: Set this to true to skip TRMNL authentication headers during local development with serverless-offline.

Backend Setup (Local Development)

Follow these steps to get the backend running locally:

1. Install Dependencies: Navigate to the project root and install all required dependencies:

2. Run Locally: To start the serverless backend locally using serverless-offline, execute:

   This command will start a local API Gateway endpoint, typically at http://localhost:3000. You can then test your API endpoints, such as http://localhost:3000/prayer-times?city=London&country=UK.

3. Local Template Preview: For developing and testing the TRMNL plugin templates (.liquid files), the project includes a preview script that renders them in a local web server:

   • yarn preview:build: Compiles the templates into static HTML files for preview.
   • yarn preview:serve: Starts a local web server (usually at http://localhost:3001) to serve the compiled templates.
   • yarn preview:watch: Monitors changes in src/templates and automatically rebuilds the preview.
   • yarn preview: Runs build, watch, and serve concurrently, providing a live-reloading development experience for templates.

TRMNL Device Setup

Once your backend is deployed (or at least your your-api-gateway-url is available from a previous cloud deployment), you can add the plugin to your TRMNL device:

1. Log in to your TRMNL account (if not already).
2. Add the configured Salah Times private plugin to your TRMNL playlists.
3. Ensure your TRMNL plugin configuration (from "TRMNL Plugin Setup" section) points to your deployed API Gateway URL. The plugin will poll https://your-api-gateway-url/prayer-times?city={city}&country={country}&method={method} (and other endpoints) to fetch prayer times and render them on your e-ink display.
4. The plugin templates, located in src/templates/trmnl-plugin/ (e.g., markup.html for full-screen, half-view-markup.html, quadrant-view-markup.html), define how the data is displayed. These are handled by the plugin-markup-handler and do not need to be manually copied to your TRMNL device; the TRMNL platform will fetch them from your configured Plugin Markup URL.