@screenly/edge-apps 1.2.1 → 1.4.0

package/README.md

@@ -140,16 +140,100 @@ signalReady()
 - `addUTMParams(url, params?)` - Add UTM parameters to URL
 - `addUTMParamsIf(url, enabled, params?)` - Conditionally add UTM parameters
 
+### Edge App Cache
+
+- `readEdgeAppCache(namespace, key)` - Read a `localStorage`-backed, namespaced last-known-good value
+- `writeEdgeAppCache(namespace, key, value)` - Write a `localStorage`-backed, namespaced last-known-good value
+
 ### 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.
 
+## Edge App Cache
+
+When an Edge App fetches data from a backend, a failure shouldn't necessarily
+break the display — falling back to the last-known-good value is often better
+than showing an error.
+
+### `readEdgeAppCache(namespace, key)` / `writeEdgeAppCache(namespace, key, value)`
+
+Read/write a `localStorage`-backed value under `namespace`, so different
+apps/caches don't collide. There is no TTL: it's meant to store the
+last-known-good value and be consulted only after a genuine fetch failure, not
+as a general-purpose expiring cache — and `localStorage` itself isn't
+guaranteed to survive a device reboot. Both fail silently (return `null` /
+no-op) if storage is unavailable, disabled, or full — so it's safe to use
+without extra error handling around it.
+
+`writeEdgeAppCache()` accepts any JSON-serializable value (object, array,
+string, number, etc.) — `WeatherData` below is just a stand-in name for
+"whatever your fetch returns," not a type this library exports.
+
+```typescript
+import {
+  readEdgeAppCache,
+  writeEdgeAppCache,
+  getSettingWithDefault,
+} from '@screenly/edge-apps'
+
+async function loadWeather() {
+  const displayErrors = getSettingWithDefault('display_errors', false)
+
+  try {
+    const response = await fetch(weatherApiUrl)
+    if (!response.ok) throw new Error(`Weather API returned ${response.status}`)
+
+    // weatherData can be any JSON-serializable shape, e.g.:
+    // { temperature: 18, description: 'Cloudy', unit: 'metric' }
+    const weatherData: WeatherData = await response.json()
+    writeEdgeAppCache('my-edge-app', 'weather', weatherData)
+    return weatherData
+  } catch (error) {
+    // When `display_errors` is on, the raw error always wins, by design, so
+    // operators can diagnose real problems instead of seeing stale data.
+    if (!displayErrors) {
+      return readEdgeAppCache<WeatherData>('my-edge-app', 'weather')
+    }
+    throw error
+  }
+}
+```
+
 ## Web Components
 
 This library includes reusable web components for building consistent Edge Apps. See the [components documentation](https://github.com/Screenly/edge-apps-library/blob/main/docs/components.md) for usage details.
 
+## Styling with Tailwind CSS
+
+Edge Apps scaffolded with `create` come with [Tailwind CSS](https://tailwindcss.com/) enabled out of the box via `@tailwindcss/vite` — no extra install or config file needed. Just add the import to your app's stylesheet:
+
+```css
+@layer theme, base, utilities;
+
+@import 'tailwindcss/theme.css' layer(theme);
+@import '@screenly/edge-apps/styles' layer(base);
+@import 'tailwindcss/utilities.css' layer(utilities);
+```
+
+> [!IMPORTANT]
+> Declare the layer order up front with `@layer theme, base, utilities;`, and import `@screenly/edge-apps/styles` (and any other unlayered base CSS) into the `base` layer. Per the CSS Cascade Layers spec, unlayered CSS always beats layered CSS regardless of selector specificity — so without this, `@screenly/edge-apps/styles`'s base rules (e.g. its `user-select: none` reset) would silently override Tailwind utility classes.
+
+Then use utility classes directly in your markup instead of writing custom CSS:
+
+```html
+<main class="flex h-full w-full items-center justify-center">
+  <h1 class="text-6xl portrait:text-4xl">Hello, Screenly!</h1>
+</main>
+```
+
+> [!IMPORTANT]
+> Inside `<auto-scaler>`, use `h-full`/`w-full` instead of `h-screen`/`w-screen`. `<auto-scaler>` renders its content into a fixed-size box (the `reference-width`/`reference-height` you pass it) and scales that box to fit the real viewport with a CSS transform. Viewport-relative utilities (`h-screen`, `w-screen`, or arbitrary `vh`/`vw` values) measure the real viewport, not the scaled box, so they won't line up with the rest of your layout. The `portrait:`/`landscape:` variants are unaffected since they're based on device orientation, which `<auto-scaler>` uses the same way.
+
+> [!WARNING]
+> Avoid `@import 'tailwindcss';` (the full package) in an Edge App. It includes Preflight, which resets `border`, `margin`, and `padding` to `0` on every element via a universal selector — including custom-element hosts. Components like `<app-header>` style themselves through `:host` in their own shadow DOM (border, padding, etc.), and Preflight's reset silently overrides that styling from outside, since the host tag itself is a normal element in your page's light DOM. Import `tailwindcss/theme.css` and `tailwindcss/utilities.css` directly instead, as shown above, to get Tailwind's utility classes without Preflight.
+
 ## 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.

package/dist/utils/edge-app-cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export declare function readEdgeAppCache<T>(namespace: string, key: string): T | null;
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export declare function writeEdgeAppCache(namespace: string, key: string, value: unknown): void;
+//# sourceMappingURL=edge-app-cache.d.ts.map

package/dist/utils/edge-app-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-app-cache.d.ts","sourceRoot":"","sources":["../../src/utils/edge-app-cache.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAU5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,IAAI,CAWN"}

package/dist/utils/edge-app-cache.js

@@ -0,0 +1,49 @@
+function getStorage() {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export function readEdgeAppCache(namespace, key) {
+    const storage = getStorage();
+    if (!storage)
+        return null;
+    try {
+        const raw = storage.getItem(`${namespace}:${key}`);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export function writeEdgeAppCache(namespace, key, value) {
+    const storage = getStorage();
+    if (!storage)
+        return;
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return;
+        storage.setItem(`${namespace}:${key}`, serialized);
+    }
+    catch {
+        // Storage disabled or quota exceeded; caller simply has nothing cached.
+    }
+}

package/dist/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from './calendar.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.js';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}

package/dist/utils/index.js

@@ -1,5 +1,6 @@
 export * from './calendar.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@screenly/edge-apps",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
   "type": "module",
   "sideEffects": [
@@ -104,7 +104,7 @@
     "jsdom": "^28.1.0",
     "offline-geocode-city": "^1.0.2",
     "panic-overlay": "^1.0.51",
-    "sharp": "^0.34.5",
+    "sharp": "^0.35.3",
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.0",

package/scripts/create-template/README.md

@@ -16,6 +16,8 @@ Install dependencies:
 {{PM_RUN}} dev
 ```
 
+Styling uses [Tailwind CSS](https://tailwindcss.com/) utility classes, enabled via the `tailwindcss/theme.css` and `tailwindcss/utilities.css` imports in `src/style.css`. Inside `<auto-scaler>`, use `h-full`/`w-full` rather than `h-screen`/`w-screen` — see the [`@screenly/edge-apps` README](https://github.com/Screenly/edge-apps-library#styling-with-tailwind-css) for details.
+
 ## Build
 
 ```bash

package/scripts/create-template/index.html

@@ -12,10 +12,10 @@
       reference-height="1080"
       orientation="auto"
     >
-      <div id="app">
+      <div id="app" class="flex h-full w-full flex-col">
         <app-header show-date></app-header>
-        <main class="content">
-          <h1 id="message"></h1>
+        <main class="flex flex-1 items-center justify-center">
+          <h1 id="message" class="text-6xl portrait:text-4xl"></h1>
         </main>
       </div>
     </auto-scaler>

package/scripts/create-template/src/style.css

@@ -1,30 +1,22 @@
-@import '@screenly/edge-apps/styles';
+@layer theme, base, utilities;
 
-* {
-  box-sizing: border-box;
-}
+@import 'tailwindcss/theme.css' layer(theme);
+@import '@screenly/edge-apps/styles' layer(base);
+@import 'tailwindcss/utilities.css' layer(utilities);
 
-body {
-  margin: 0;
-  padding: 0;
-  overflow: hidden;
-  font-family: 'Inter', system-ui, sans-serif;
-}
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
 
-#app {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100%;
-}
-
-.content {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
+  body {
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+    font-family: 'Inter', system-ui, sans-serif;
+  }
 
-#message {
-  color: var(--theme-color-primary, #972eff);
+  #message {
+    color: var(--theme-color-primary, #972eff);
+  }
 }