paperlesspaper Integrations

This repository contains a Docker-ready collection of paperlesspaper Open Integrations. Each integration is a small HTML/CSS/JS provider that exposes a manifest, a render page, and optionally a settings page or server-side data route.

The structure is based on the official paperlesspaper Open Integration overview. That documentation defines the core contract this repo follows: a public config.json, a deterministic render.html surface for screenshot generation, optional settings.html, and loading markers that let paperlesspaper wait until async content is ready.

Quick Start

Install dependencies and start the local provider:

npm install
npm start

The server listens on http://localhost:3000 by default. Check the health endpoint with:

curl http://localhost:3000/health

How It Works

Integrations live in applications/<slug>/.

File	Purpose
config.json	Install manifest consumed by paperlesspaper.
render.html	Full-screen display surface captured for the ePaper image.
settings.html	Optional custom settings UI embedded by paperlesspaper.
api/data.js	Optional server-side data loader exposed at /<slug>/api/data.
languages/*.json	Localized labels and descriptions.
assets/*	Integration-specific PNG icons and static assets.

The Express server maps every application folder to predictable URLs:

/:slug/             -> applications/:slug/render.html
/:slug/render.html  -> applications/:slug/render.html
/:slug/config.json  -> applications/:slug/config.json
/:slug/api/data     -> applications/:slug/api/data.js
/assets/*           -> shared helper assets

Render pages use shared assets from @paperlesspaper/openintegration, copied into public/ during npm install and Docker builds.

Available Integrations

The production base URL is:

https://integrations.paperlesspaper.de

For example, the Quote manifest is available at https://integrations.paperlesspaper.de/quote/config.json, and its interactive demo is available at https://integrations.paperlesspaper.de/quote/run.

For local development, use http://localhost:3000/<slug>/config.json.

Icon	Integration	Demo	Manifest URL	Description
	Airtable	run	config	Shows one or more Airtable tables as compact eInk-friendly data views.
	Apple Photos Gallery	run	config	Shows a random or numbered image from a public iCloud shared album.
	Astronauts	run	config	Shows the current people in space, grouped by spacecraft or station.
	Bible Verses	run	config	Shows a random Bible verse or a curated verse of the day.
	Bike Commute Card	run	config	Shows rain window, wind, route status, and air quality for a bike commute.
	Bird of the Day	run	config	Shows one deterministic daily bird with clean side-profile artwork and compact Wikipedia-sourced facts.
	Chore Wheel	run	config	Shows a rotating household chore wheel that assigns chores to members deterministically by day or week.
	Constellations in the Sky	run	config	Shows a seasonal constellation sky map with highlighted star patterns and labels.
	Countdown Card	run	config	Shows a configurable countdown or count-up with days, time, and optional progress.
	Country of the Day	run	config	Shows one deterministic daily country with a flag, capital, region, area, languages, currency, and compact map-friendly facts.
	Daily Buddhism Wisdom	run	config	Shows a daily Buddhist wisdom quote from Buddha API.
	Day Calendar	run	config	Shows the current day with optional demotivational quotes or funny facts from the paperlesspaper DayCalendar app.
	Deutsche Bahn Abfahrten	run	config	Shows a compact station-board view of upcoming realtime departures for a Deutsche Bahn station.
	Dinosaur of the Day	run	config	Shows one deterministic daily dinosaur with display-friendly silhouette artwork and compact Wikipedia-sourced facts.
	Duden Wort des Tages	run	config	Shows Duden's German word of the day with meaning, usage, origin, type, and frequency.
	DWD Pollenflug	run	config	Shows current DWD pollen forecasts for a German forecast region.
	Finance Snapshot	run	config	Shows a compact market dashboard with commodities, crypto, currencies, energy, indices, ETFs, stocks, and trend markers.
	Formula 1 Races	run	config	Shows the upcoming Formula 1 Grand Prix with circuit details, date, session times, and a track image.
	Google Calendar	run	config	Displays upcoming Google Calendar events from host-provided calendar data.
	Google Sheet Table	run	config	Shows matching rows from a public Google Sheet as a compact Date, Name, and Group table.
	Guest Mode Card	run	config	Shows a guest-ready welcome card with scannable Wi-Fi QR, checkout time, house rules, nearby picks, smart-home hints, and emergency contact.
	Immich Photos	run	config	Shows a random, newest, or oldest photo from an Immich server.
	Kids Fact Card	run	config	Displays a kid-friendly dinosaur, space, or animal fact with a deterministic daily thinking prompt.
	Losung	run	config	Shows the daily Losung and Lehrtext Bible readings from losungen.de.
	Mastodon	run	config	Shows Mastodon timelines, hashtag streams, and profile feeds as compact eInk-friendly social cards.
	Moon Phase	run	config	Shows the moon phase for a chosen date, with illumination, moon age, hemisphere, and an optional next major phase estimate.
	Newsstand	run	config	Shows a fresh newspaper front page from Riley Walz's Papers archive.
	NFL Scoreboard	run	config	Shows NFL scores, fixtures, live status, favorite-team highlights, and league leaders from ESPN.
	Opening Hours	run	config	Shows current opening status, today's hours, and the weekly schedule for a place.
	Quote	run	config	Shows a deterministic daily quote.
	Simple Calendar	run	config	Shows a configurable monthly calendar inspired by the TRMNL Simple Calendar recipe.
	Simple Text	run	config	Displays configurable plain text or markdown notes with typography, alignment, and framing controls.
	Soccer Standings	run	config	Shows European soccer league standings with favorite-team focus, crest-style markers, compact table rows, and an optional markdown note.
	Spacecraft of the Day	run	config	Shows one deterministic daily spacecraft with centered portrait artwork and compact mission facts.
	The Onion - Editorial Cartoon	run	config	Shows a recent editorial cartoon from The Onion's Cartoons section.
	Tour de France	run	config	Shows the current, next, or selected Tour de France 2026 stage with route details, profile imagery, and best-effort official ranking data.
	Train of the Day	run	config	Shows one deterministic daily train with first-car artwork and compact facts, focused mostly on European trains.
	Travel Map	run	config	Shows a personal visited map for countries, US states, or German Bundesländer with year-based coloring.
	Tree of the Day	run	config	Shows one deterministic daily tree with generated botanical artwork and compact Wikipedia-sourced facts.
	Uptime Kuma Monitor	run	config	Shows public Uptime Kuma status pages with monitor states, 24-hour uptime, heartbeat history, incidents, and maintenance windows.
	Waste Collection Schedule	run	config	Shows upcoming waste collection dates from an ICS/iCal feed or manual recurring schedules.
	Weather	run	config	Shows current weather and a three-day forecast from Open-Meteo.
	World Cup 2026	run	config	Shows World Cup 2026 fixtures, latest results, and the favorite-team group table in an eInk-friendly tournament dashboard.
	Your Life in Weeks	run	config	Shows a week-by-week lifetime grid from a configurable birth date, with age, progress, and current-week markers.
	XKCD	run	config	Shows the latest, random, or offset XKCD comic.

Development

Use the render URL while building an integration:

http://localhost:3000/<slug>/

Use the manifest URL when installing it in paperlesspaper:

http://localhost:3000/<slug>/config.json

Open Integrations should render within 100vw by 100vh, avoid browser-only chrome, and keep layout stable for predictable screenshots. If an integration fetches data, create the loading marker immediately and only mark the page loaded once content is ready:

<div id="website-has-loading-element"></div>
<div id="website-has-loaded">ready</div>

Screenshots

Regenerate local variant screenshots and update configVariants in application manifests:

npm run screenshots

Useful filters while iterating:

npm run screenshots -- --config-only
npm run screenshots -- --app weather --resolution 800x480

Generated screenshots are ignored by git under output/ and applications/*/screenshots/.

Docker

Build and run the container directly:

npm run docker:build
npm run docker:run

Or use Docker Compose:

docker compose up --build

Hosting

When hosting this provider for real devices, expose it over HTTPS and make sure paperlesspaper can fetch each integration manifest from the browser. The public install URL on the production deployment looks like:

https://integrations.paperlesspaper.de/<slug>/config.json

Some integrations call upstream APIs from api/data.js. Keep credentials in environment variables or user-provided settings, not in committed files. .env, node_modules, generated output, and local workspace files are intentionally ignored.

Adding An Integration

1. Create applications/<slug>/.
2. Add a config.json manifest with name, version, description, renderPage, icon, and any settings schema.
3. Add a square transparent PNG icon at assets/icon.png and reference it as "./assets/icon.png".
4. Add render.html and make it deterministic at the target viewport size.
5. Add settings.html only when the built-in schema fields are not enough.
6. Add api/data.js only when data should be fetched server-side.
7. Run npm run screenshots -- --app <slug> to refresh variants.

Use the smallest provider that works: plain manifest settings first, a custom settings page when the user experience needs it, and server routes only when browser-side rendering cannot call the upstream service directly.