From 195702e3573ba849abac589a6e93ea89bab73878 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Fri, 17 Jul 2026 09:56:33 -0700 Subject: [PATCH 1/4] docs(edge-apps): add Sentry error reporting guidance - document sentry_dsn as a global secret setting - describe setupSentry/reportError usage from @screenly/edge-apps/utils - reference salesforce-app and powerbi-app implementations --- .claude/skills/create-an-edge-app/SKILL.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index c6c99bcf8..6d9613476 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -35,6 +35,17 @@ To develop locally (real credentials aren't present), set up a **super simple** Both paths feed the same `getCredentials()` — the Edge App code does not change between them. +## Error Reporting (Sentry) + +Every Edge App should support optional Sentry error reporting, gated behind a `sentry_dsn` setting that no-ops when unset. + +- Add a `sentry_dsn` setting to `screenly.yml`/`screenly_qc.yml`: `type: secret`, `optional: true`, `is_global: true` (shared across app instances rather than configured per-instance). Use the structured `help_text` format with `advanced: true` and a short description of what's being reported. +- Call `setupSentry('', { : { ...relevant settings for context... } })` from `@screenly/edge-apps/utils` once, near the top of `main.ts`, before other startup logic. +- Report failures with `reportError(error, { source: '' })` from `@screenly/edge-apps/utils` at meaningful failure points (credential refresh, content load, API errors) — not for expected or already-handled states. +- Dedupe repeated consecutive failures of the same kind (e.g. only report the first of a run of identical background-refresh errors) so retry loops don't spam Sentry. +- Requires `@screenly/edge-apps` `^1.1.0` or later. +- See [Screenly/salesforce-app](https://github.com/Screenly/salesforce-app) (`src/main.ts`, `src/credentials.ts`) and [Screenly/powerbi-app](https://github.com/Screenly/powerbi-app) (`src/main.ts`, `src/services.ts`) for reference implementations. + ## Testing - Write tests before the feature, then make them pass. Every app ships an `e2e/` directory (Playwright); add cases there for the behavior you build. From 8127930b11d657f4b32cd82d3d8a3739bead8c48 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Fri, 17 Jul 2026 10:18:21 -0700 Subject: [PATCH 2/4] docs(edge-apps): clarify sentry_dsn setting example and syntax - add explicit YAML example for the sentry_dsn setting - fix setupSentry example to use valid syntax - reference src/main.ts consistently with the rest of the doc --- .claude/skills/create-an-edge-app/SKILL.md | 23 +++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 6d9613476..4041ba77f 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -39,9 +39,26 @@ Both paths feed the same `getCredentials()` — the Edge App code does not chang Every Edge App should support optional Sentry error reporting, gated behind a `sentry_dsn` setting that no-ops when unset. -- Add a `sentry_dsn` setting to `screenly.yml`/`screenly_qc.yml`: `type: secret`, `optional: true`, `is_global: true` (shared across app instances rather than configured per-instance). Use the structured `help_text` format with `advanced: true` and a short description of what's being reported. -- Call `setupSentry('', { : { ...relevant settings for context... } })` from `@screenly/edge-apps/utils` once, near the top of `main.ts`, before other startup logic. -- Report failures with `reportError(error, { source: '' })` from `@screenly/edge-apps/utils` at meaningful failure points (credential refresh, content load, API errors) — not for expected or already-handled states. +- Add a `sentry_dsn` setting to `screenly.yml`/`screenly_qc.yml` as a global secret that no-ops when unset: + ```yaml + settings: + sentry_dsn: + type: secret + title: Sentry DSN + optional: true + is_global: true + help_text: + schema_version: 1 + properties: + advanced: true + help_text: Sentry DSN for reporting errors. Leave empty to disable. + type: string + ``` +- Call `setupSentry` from `@screenly/edge-apps/utils` once, near the top of `src/main.ts`, before other startup logic, passing the app name and any settings useful as context: + ```ts + setupSentry('app-name', { 'app-name': { contentId: screenly.settings.content_id } }) + ``` +- Report failures with `reportError(error, { source: 'short-context' })` from `@screenly/edge-apps/utils` at meaningful failure points (credential refresh, content load, API errors) — not for expected or already-handled states. - Dedupe repeated consecutive failures of the same kind (e.g. only report the first of a run of identical background-refresh errors) so retry loops don't spam Sentry. - Requires `@screenly/edge-apps` `^1.1.0` or later. - See [Screenly/salesforce-app](https://github.com/Screenly/salesforce-app) (`src/main.ts`, `src/credentials.ts`) and [Screenly/powerbi-app](https://github.com/Screenly/powerbi-app) (`src/main.ts`, `src/services.ts`) for reference implementations. From 1ed6fd219bf0e9fdd7f083ee774f350d3e70f934 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Fri, 17 Jul 2026 10:31:15 -0700 Subject: [PATCH 3/4] docs(edge-apps): use a universal metadata field in setupSentry example - replace app-specific content_id with screenly.metadata.screen_name, which is available in every Edge App --- .claude/skills/create-an-edge-app/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 4041ba77f..fb0a8b413 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -54,9 +54,9 @@ Every Edge App should support optional Sentry error reporting, gated behind a `s help_text: Sentry DSN for reporting errors. Leave empty to disable. type: string ``` -- Call `setupSentry` from `@screenly/edge-apps/utils` once, near the top of `src/main.ts`, before other startup logic, passing the app name and any settings useful as context: +- Call `setupSentry` from `@screenly/edge-apps/utils` once, near the top of `src/main.ts`, before other startup logic, passing the app name and any settings or metadata useful as context: ```ts - setupSentry('app-name', { 'app-name': { contentId: screenly.settings.content_id } }) + setupSentry('app-name', { 'app-name': { screenName: screenly.metadata.screen_name } }) ``` - Report failures with `reportError(error, { source: 'short-context' })` from `@screenly/edge-apps/utils` at meaningful failure points (credential refresh, content load, API errors) — not for expected or already-handled states. - Dedupe repeated consecutive failures of the same kind (e.g. only report the first of a run of identical background-refresh errors) so retry loops don't spam Sentry. From 040702594bff1d68f10bcac915909555084fc80e Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Fri, 17 Jul 2026 10:34:49 -0700 Subject: [PATCH 4/4] docs(edge-apps): polish Sentry guidance wording - scope the guidance to new apps rather than all apps - make the help_text example copy-pasteable --- .claude/skills/create-an-edge-app/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index fb0a8b413..6c4e1d0a4 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -37,7 +37,7 @@ Both paths feed the same `getCredentials()` — the Edge App code does not chang ## Error Reporting (Sentry) -Every Edge App should support optional Sentry error reporting, gated behind a `sentry_dsn` setting that no-ops when unset. +New Edge Apps should support optional Sentry error reporting, gated behind a `sentry_dsn` setting that no-ops when unset. - Add a `sentry_dsn` setting to `screenly.yml`/`screenly_qc.yml` as a global secret that no-ops when unset: ```yaml @@ -51,7 +51,7 @@ Every Edge App should support optional Sentry error reporting, gated behind a `s schema_version: 1 properties: advanced: true - help_text: Sentry DSN for reporting errors. Leave empty to disable. + help_text: Sentry DSN for reporting errors. Leave empty to disable. type: string ``` - Call `setupSentry` from `@screenly/edge-apps/utils` once, near the top of `src/main.ts`, before other startup logic, passing the app name and any settings or metadata useful as context: