@screenly/edge-apps

A TypeScript library for interfacing with the Screenly Edge Apps API.

Installation

Note

Requires Node.js >= 20.6.0.

npm install @screenly/edge-apps

Or with Bun:

bun add @screenly/edge-apps

Creating a New Edge App

Scaffold a new Edge App without installing anything first:

npx @screenly/edge-apps create my-edge-app

Or with Bun:

bunx @screenly/edge-apps create my-edge-app

The package manager used to invoke the command is detected automatically, so the generated package.json scripts are wired up to match (npm run ... vs. bun run ...). This generates a minimal Edge App with a screenly.yml manifest, index.html, and a src/main.ts entry point wired up to this library.

Pass options after the directory name, for example:

npx @screenly/edge-apps create my-edge-app --description "My Edge App" --author "Jane Doe"

Option	Description
--description <text>	Description used in package.json, screenly.yml, and README.md
--author <text>	Author name added to package.json
--pm <npm|bun>	Force a package manager instead of auto-detecting it
--force	Write into an existing, non-empty directory
--skip-install	Skip installing dependencies after scaffolding

Note

Running edge-apps-scripts create with no directory argument instead replaces {{APP_NAME}}-style placeholders in the current project — this is used by Edge App template repositories after cloning, and is unrelated to scaffolding a brand new app.

No test files are included — test/test:unit work out of the box on an empty suite; add your own under src/ when you have something to test.

Local Development Setup

When developing Edge Apps locally using the library from this repository, you should link the package.

First, in the root of this repository:

npm install
npm run build
npm link

Then in your Edge App directory:

cd /path/to/your-edge-app
npm link @screenly/edge-apps

To unlink the package when you're done with local development, run the following in your Edge App directory:

npm install

Quick Start

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

setupTheme()
const metadata = getMetadata()
signalReady()

Core Functions

Theme & Branding

• setupTheme() - Apply theme colors to CSS custom properties
• setupBrandingLogo() - Fetch and process branding logo
• setupBranding() - Setup complete branding (colors and logo)

Settings

• getSettings() - Get all settings
• getSetting<T>(key) - Get specific setting with type safety
• getSettingWithDefault<T>(key, default) - Get setting with fallback
• signalReady() - Signal app is ready for display

Metadata

• getMetadata() - Get all screen metadata
• getScreenName()
• getHostname()
• getLocation()
• getScreenlyVersion()
• getTags()
• hasTag(tag)
• getFormattedCoordinates()
• getHardware() - Get hardware type as Hardware enum (Anywhere, RaspberryPi, or ScreenlyPlayerMax)

Location & Localization

• getTimeZone() - Get timezone from GPS coordinates
• getLocale() - Get locale from location
• formatCoordinates(coords) - Format coordinates as string
• formatLocalizedDate(date, locale) - Format date for locale
• formatTime(date, locale, timezone) - Format time for locale
• getLocalizedDayNames(locale) - Get day names for locale
• getLocalizedMonthNames(locale) - Get month names for locale
• detectHourFormat(locale) - Detect 12h/24h format for locale

UTM Tracking

• addUTMParams(url, params?) - Add UTM parameters to URL
• addUTMParamsIf(url, enabled, params?) - Conditionally add UTM parameters

Error Reporting (Sentry)

• setupSentry(app, contexts?) - Initialize Sentry using the sentry_dsn setting; sets the edge_app tag, hostname, and any additional contexts. No-ops if sentry_dsn is not configured.
• scrubSensitiveData(event) - Sentry beforeSend hook that redacts values of settings keys matching token, secret, password, or credential with [REDACTED]. Drops the event if it cannot be safely serialized.
• reportError(error, context?) - Capture an exception via Sentry with optional extra context.

Web Components

This library includes reusable web components for building consistent Edge Apps. See the components documentation for usage details.

Edge Apps Scripts CLI

This package provides the edge-apps-scripts CLI tool for running shared development commands across all Edge Apps. It includes centralized ESLint configuration to avoid duplication.

Available Commands

Development Server

Start the Vite development server with mock data from screenly.yml and mock-data.yml:

npm run dev

Building

npm run build

Linting

To lint your Edge App:

npm run lint

To lint and automatically fix issues:

npm run lint -- --fix

Type Checking

Run TypeScript type checking:

npm run type-check

Command-Line Utilities for Edge Apps

• This library provides utilities to help with common Edge App tasks.
• The CLI uses the shared ESLint configuration from @screenly/edge-apps, so you don't need to maintain your own eslint.config.ts
• The build commands assume your Edge App has index.html as the entry point
• Build output will be generated in the dist/ directory

It is recommended to add the following scripts to your Edge App's package.json:

{
  "scripts": {
    "dev": "edge-apps-scripts dev",
    "build": "edge-apps-scripts build",
    "build:dev": "edge-apps-scripts build:dev",
    "lint": "edge-apps-scripts lint",
    "type-check": "edge-apps-scripts type-check",
    "deploy": "npm run build && screenly edge-app deploy --path=dist/"
  }
}

Note

Feel free to customize the scripts as needed for your Edge App. You could also define your own configs like eslint.config.ts, tsconfig.json, or vite.config.ts if you need more control.

Testing

import { setupScreenlyMock, resetScreenlyMock } from '@screenly/edge-apps/test'

beforeEach(() => {
  setupScreenlyMock({ screen_name: 'Test Screen' }, { theme: 'dark' })
})

afterEach(() => {
  resetScreenlyMock()
})

Types

import type {
  Hardware,
  ScreenlyMetadata,
  ScreenlySettings,
  ScreenlyObject,
  ThemeColors,
  BrandingConfig,
  UTMParams,
} from '@screenly/edge-apps'

Development

npm install      # Install dependencies
npm test         # Run tests
npm run build    # Build library