Edge Apps library release notes | Screenly

Edge Apps library 26.8.0: A new captureScreenshot helper takes an Edge App screenshot in 1 call

Tue, 01 Sep 2026 00:00:00 +0000

A screenshot spec for an Edge App does the same 7 things for every resolution: open a browser context at the right size, fix the clock, mock screenly.js, load the page, wait for the network to go quiet, save the image, and close the context. captureScreenshot() does all of it, and your spec keeps only what’s specific to your app:

import { test } from '@playwright/test'
import {
 captureScreenshot,
 createMockScreenlyForScreenshots,
 RESOLUTIONS,
} from '@screenly/edge-apps/test/screenshots'

const { screenlyJsContent } = createMockScreenlyForScreenshots()

for (const { width, height } of RESOLUTIONS) {
 test(`screenshot ${width}x${height}`, async ({ browser }) => {
 await captureScreenshot(browser, {
 width,
 height,
 filenamePrefix: 'menu-board',
 screenlyJsContent,
 setupMocks: async (page) => {
 await page.route('**/api/prices**', (route) =>
 route.fulfill({ status: 200, body: '{"items":[]}' }),
 )
 },
 })
 })
}

Each run writes screenshots/menu-board-1920x1080.png and so on, 1 file per resolution. setupMocks runs before the page loads, so your routes are in place for the first request. Leave it out when there’s nothing app-specific to mock.

Keep test() in your own spec file, as above. That way Playwright reports failures against your file and line, not the library’s.

Apps made with npx @screenly/edge-apps create from this release on get a spec that already uses it.

Edge Apps library 26.8.0: The library's version numbers moved to CalVer

Tue, 01 Sep 2026 00:00:00 +0000

Library releases are numbered by year and month now, so the release after 1.5.0 is 26.8.0. That’s the same scheme Screenly, ScreenlyOS, and the CLI use.

Nothing about the library’s behavior changes with the numbering, and a version you’ve already pinned keeps resolving to exactly what it did before.

If this affects you: a range like ^1.5.0 in your Edge App’s package.json won’t match a release again. Change it to ^26.8.0, which covers releases through the end of 2026. The first release of 2027 will be 27.1.0.

Edge Apps library 1.5.0: A new isLightColor helper picks readable text for any brand color

Wed, 19 Aug 2026 00:00:00 +0000

Your app doesn’t choose the accent color. Each customer sets their own in screenly_color_accent, and the same app has to put readable text on a pale yellow brand and on a navy one. isLightColor() tells you which you’re dealing with:

import { isLightColor, setupTheme } from '@screenly/edge-apps'

const { primary } = setupTheme()
document.body.classList.toggle('on-light-brand', isLightColor(primary))

It returns true when a color needs dark text and false when it needs light text. The answer comes from the WCAG relative luminance formula rather than an average of the red, green, and blue values, so it ranks colors the way people see them. Pure yellow and pure blue have similar channel totals and land on opposite sides.

It accepts hex (#abc, #aabbcc, #aabbccdd) and numeric rgb() or rgba() strings, and ignores alpha. Named colors and percentage channels aren’t supported. Anything it can’t read returns false instead of throwing, so a malformed setting can’t stop a screen from rendering.

Edge Apps library 1.4.0: Edge Apps can keep showing the last good data when a fetch fails

Sat, 01 Aug 2026 00:00:00 +0000

A weather app on a lobby screen that loses its API for 10 minutes has 2 choices: show an error to everyone walking past, or keep showing the last forecast it had. writeEdgeAppCache() and readEdgeAppCache() make the second one a few lines of code:

import {
 getSettingWithDefault,
 readEdgeAppCache,
 writeEdgeAppCache,
} from '@screenly/edge-apps'

async function loadWeather() {
 try {
 const response = await fetch(weatherApiUrl)
 if (!response.ok) throw new Error(`Weather API returned ${response.status}`)

 const weather = await response.json()
 writeEdgeAppCache('weather-app', 'forecast', weather)
 return weather
 } catch (error) {
 if (getSettingWithDefault('display_errors', false)) throw error
 return readEdgeAppCache('weather-app', 'forecast')
 }
}

Values are stored in the player’s localStorage as JSON under namespace:key, so 2 apps, or 2 caches in one app, don’t overwrite each other. Anything JSON can hold works as a value.

The cache is for fallback, not freshness. Nothing expires, so read it only after a real failure, and expect it to be empty after the player restarts. Both functions fail quietly: readEdgeAppCache() returns null when there’s nothing usable, and writeEdgeAppCache() does nothing when storage is full or unavailable, so neither needs its own try.

Edge Apps library 1.3.0: New Edge Apps come with Tailwind CSS set up

Tue, 28 Jul 2026 00:00:00 +0000

An Edge App made with npx @screenly/edge-apps create now styles its page with Tailwind CSS utility classes, so you can lay out a screen in the markup without writing a stylesheet first. The Tailwind plugin was already part of the edge-apps-scripts build, so an existing app needs only the imports. Put these at the top of your stylesheet:

@layer theme, base, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import '@screenly/edge-apps/styles' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities);

Keep the layer order line and the layer(base) on the library’s styles. Without them, the library’s base styles win over your utility classes, whatever their specificity.

Don’t use @import 'tailwindcss'; on its own. It includes Tailwind’s Preflight reset, which strips the borders and padding that components like <app-header> set for themselves.

Inside <auto-scaler>, size things with h-full and w-full rather than h-screen and w-screen. <auto-scaler> draws your app at its reference size and scales the result to fit the display, so viewport units measure the wrong box. The portrait: and landscape: variants work as expected:

<main class="flex h-full w-full items-center justify-center">
 <h1 class="text-6xl portrait:text-4xl">Today's specials</h1>
</main>

Edge Apps library 1.2.1: The app header shows the logo without the screen name

Tue, 21 Jul 2026 00:00:00 +0000

<app-header> shows the logo without the screen name next to it. If your app needs the name on screen, <brand-logo show-name> still renders it.

Edge Apps library 1.2.0: A new create command scaffolds an Edge App in 1 step

Sun, 19 Jul 2026 00:00:00 +0000

Starting an Edge App used to mean cloning a template repository and replacing its placeholders. Now 1 command gives you a project that builds:

npx @screenly/edge-apps create my-edge-app
cd my-edge-app
npm run dev

With Bun, run bunx @screenly/edge-apps create my-edge-app instead. The command notices which package manager started it and writes the package.json scripts and test setup to match. --pm npm or --pm bun overrides that.

The new directory has:

a screenly.yml manifest with a message setting and a sentry_dsn setting
index.html with <auto-scaler> and <app-header> already on the page
src/main.ts, which applies the theme, reads the message setting, and signals ready
scripts for dev (with the CORS proxy running alongside), build, lint, format, type-check, screenshots, and deploy
a Playwright spec under e2e/ for screenshots at every supported resolution

Dependencies are installed for you, at the versions the library itself was released with.

Option	What it does
`--description <text>`	Sets the description in `package.json`, `screenly.yml`, and `README.md`
`--author <text>`	Sets the author in `package.json`
`--pm <npm\|bun>`	Picks the package manager instead of detecting it
`--force`	Writes into a directory that already has files in it
`--skip-install`	Skips installing dependencies

Running edge-apps-scripts create with no directory still does what it did before: it fills in the {{APP_NAME}}-style placeholders in the current project, for template repositories you’ve already cloned.

Edge Apps library 1.1.2: The edge-apps-scripts commands run on Vite 8

Thu, 16 Jul 2026 00:00:00 +0000

Improvements

edge-apps-scripts dev, build, and build:dev run on Vite 8. If your Edge App brings its own vite.config.ts or Vite plugins, check them against Vite 8 when you upgrade.

Edge Apps library 1.1.1: The README lists the error reporting helpers

Sun, 21 Jun 2026 00:00:00 +0000

Improvements

The README now lists the error reporting helpers that came with Sentry support in 1.1.0: setupSentry, scrubSensitiveData, and reportError.

Edge Apps library 1.1.0: Edge Apps can send their errors to your own Sentry project

Fri, 19 Jun 2026 00:00:00 +0000

An Edge App that fails on a screen in another building usually fails quietly. Nobody is standing in front of it with the developer tools open. With setupSentry() and reportError(), those errors land in your own Sentry project instead, with enough context to tell which screen sent them.

Add a sentry_dsn setting to screenly.yml, set it to your project’s DSN in Screenly, and call setupSentry() once when the app starts:

settings:
 sentry_dsn:
 type: secret
 title: Sentry Client Key
 optional: true
 is_global: true

import { setupSentry, reportError } from '@screenly/edge-apps'

setupSentry('menu-board')

try {
 await refreshPrices()
} catch (error) {
 reportError(error, { source: 'price-feed' })
}

Every event is tagged with edge_app (the name you pass) and the screen’s hostname, which is also set as the Sentry user, so one screen’s errors group together. The optional second argument to setupSentry() attaches contexts of your own, such as the URL a report was embedded from. The second argument to reportError() goes in as extra data on that event.

Before an event leaves the screen, the value of any setting whose key contains token, secret, password, or credential is replaced with [REDACTED] wherever it appears in the event. If an event can’t be checked that way, it isn’t sent. The same filter is exported as scrubSensitiveData() if you initialize Sentry yourself and want it as your beforeSend.

Leave sentry_dsn empty and setupSentry() does nothing, so the same build runs with or without error reporting. It reports errors only, with no performance tracing.

Edge Apps library 1.0.0: edge-apps-scripts runs on Node.js and npm

Sat, 02 May 2026 00:00:00 +0000

Until this release, edge-apps-scripts only ran under Bun. If your team already had Node.js everywhere, building an Edge App meant installing a second runtime first. Now the library installs and runs with npm on Node.js 20.6.0 or later:

npm install @screenly/edge-apps
npm run dev
npm run build

Every command works the same way it did under Bun: dev, build, build:dev, lint, type-check, screenshots, and create. The recommended scripts for your Edge App’s package.json are unchanged apart from deploy, which now reads npm run build && screenly edge-app deploy --path=dist/.

Bun still works. bun add @screenly/edge-apps and bun run dev read the same package.json scripts, so a Bun project can upgrade without changing anything except the CORS proxy script covered in the next entry.

To link a local copy of the library while you work on it, run npm install, npm run build, and npm link in the library, then npm link @screenly/edge-apps in your Edge App.

Edge Apps library 1.0.0: The CORS proxy is an edge-apps-scripts command now

Sat, 02 May 2026 00:00:00 +0000

The local CORS proxy has its own command:

{
 "scripts": {
 "cors-proxy-server": "edge-apps-scripts cors-proxy"
 }
}

It still listens on 0.0.0.0:8080 by default, and HOST and PORT change that. Put the target URL after the proxy’s address, as before: http://localhost:8080/https://api.example.com/feed.

The proxy also follows redirects now. When an API answers a GET or HEAD request with a 301 to 308, the proxy fetches the new location and returns that response to your app, up to 10 redirects deep. After 10 it stops and returns a 508 with Too many redirects. Other methods get the redirect response itself, unchanged.

If this affects you: the file cors-proxy-server.ts is gone from the package. If your package.json runs it directly, replace that script with edge-apps-scripts cors-proxy as shown above.