BYOS Next.js for TRMNL 🖥️

🚀 Overview

BYOS (Build Your Own Server) Next.js is a Next.js implementation that powers device management, playlist-driven content scheduling, and on-demand BMP generation for e-ink displays.

✨ Features

• Device management UI with MAC/API key registration, status tracking, and refresh scheduling.
• Playlist-based screen rotation with time and weekday rules, custom durations, and per-device assignment.
• On-demand screen rendering to 1-bit BMP via Takumi/Satori with caching and revalidation.
• Postgres backed persistence for devices, logs, and playlists.
• Recipes gallery to prototype screens and compare direct vs. bitmap rendering before pushing to hardware.
• Tailwind v4 + TypeScript + Next.js 16 + React 19; Biome lint/format baseline.
• Docker Compose for app + Postgres; deploy-ready Vercel button with Supabase/Neon integration.

Table of Contents

• BYOS Next.js for TRMNL 🖥️
  • 🚀 Overview
    • ✨ Features
  • Table of Contents
  • Highlights
  • Demo & Screens
  • Quickstart
    • Deploy to Vercel
    • Run with Docker Compose (app + Postgres)
    • Run Locally
  • Environment
    • Database Options
  • Project Structure
  • Playlists
  • Recipes
  • Documentation
  • Roadmap
  • Support & Feedback
  • License

Highlights

• Dynamic BMP generation with Next.js 16, React 19, Tailwind CSS v4, and TypeScript.
• Supabase-backed device management, logging, and playlist scheduling.
• No-DB fallback mode for quickly previewing screens without a database.
• Docker Compose support for local PostgreSQL.
• Recipes gallery for rapid screen prototyping before deploying to devices.
• Clean codebase with Biome linting and formatting.

Demo & Screens

• Live demo: https://byos-next-demo.vercel.app
• Overview UI: public/byos-nextjs-overview.png
• Device UI: public/byos-nextjs-device.png

Quickstart

Deploy to Vercel

1. Click the Vercel button above.
2. Link a Supabase or Neon project when prompted.
3. Deploy, then open the app and initialize tables.
4. Point your TRMNL device at the deployed URL.
5. Sync environment variables locally via vercel link and vercel env pull if you also develop on your machine.

Run with Docker Compose (app + Postgres)

export POSTGRES_PASSWORD=your_password
docker-compose up -d
# visit http://localhost:3000

Run Locally

git clone https://github.com/usetrmnl/byos_next
cd byos_next
pnpm install

Start the dev server:

pnpm dev

Format/lint:

pnpm lint

Environment

Create .env.local with the keys you need. Common variables:

DATABASE_URL
POSTGRES_PASSWORD

Database Options

• Supabase or Neon: run migrations in migrations/ in order to create tables and playlist support.
• Docker/Postgres: set POSTGRES_PASSWORD, run docker-compose up -d.
• No-DB mode: run pnpm dev without DB env vars to preview screens only (device management disabled).

Project Structure

• app/ - Next.js routes and screens (including /recipes).
• components/ - UI components.
• migrations/ - SQL migrations for Postgres.
• public/ - Static assets and screenshots.
• scripts/, utils/, lib/ - helpers for rendering, caching, and device logic.
• docs/api.md - HTTP API reference.

Playlists

• Schedule screens by time and weekday with custom durations.
• Assign playlists to devices to rotate content automatically.
• Enable playlist mode per device in the UI.

Recipes

Visit /recipes to browse screens and compare direct vs. bitmap rendering. To add one:

1. Create a folder under app/recipes/screens.
2. Add your component and data fetching logic.
3. Register it in app/recipes/screens.json.

See docs/recipes.md for more detail.

Documentation

• API endpoints and payloads: docs/api.md
• Recipes reference: app/recipes/README.md
• Contributing guide: CONTRIBUTING.md

Roadmap

• Better recipe management system
• Compatibility with TRMNL recipes

Support & Feedback

• GitHub Issues: https://github.com/usetrmnl/byos_next/issues
• Discussions: https://github.com/usetrmnl/byos_next/discussions
• Email: [email protected]
• TRMNL Discord: reply to the maintainer thread.

License

MIT - see LICENSE.