From fd0955458a7e56eaf1ff602a9ebcf0f2fd16803a Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Sun, 19 Jul 2026 12:16:17 -0700 Subject: [PATCH 1/4] docs: recommend the create-scaffold generator for new Edge Apps - scaffold new Edge Apps first with 'bunx @screenly/edge-apps create' instead of starting from a reference app - keep consulting reference apps for anything past the generator's basic output (integrations, Sentry, screenly_qc.yml, complex UI) - update the id-registration step to match the generator's actual behavior (no blank id field, no screenly_qc.yml by default) --- .claude/skills/create-an-edge-app/SKILL.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 6c4e1d0a4..75af6e0f4 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -8,8 +8,13 @@ description: Use when scaffolding a new Screenly Edge App — covers the templat ## When Creating an Edge App - If you're one of the maintainers of this repository, it's encouraged to create the new Edge App in its own standalone GitHub repo under the Screenly org, rather than inside this monorepo's `edge-apps/` directory. -- Scaffold the new Edge App by starting from one of the apps in the [Reference Apps](#reference-apps) section below — pick the closest match in complexity and adapt it, following the `kebab-case` naming convention for the app name. -- After scaffolding, add an `id` field to `screenly.yml` and `screenly_qc.yml` before running `bun run dev`. +- It's recommended to scaffold the new Edge App first with the `@screenly/edge-apps` create-scaffold generator, following the `kebab-case` naming convention for the app name: + ```bash + bunx @screenly/edge-apps create + ``` + This produces a minimal, working app — manifest, `index.html`, `src/main.ts`, and the standard dev/build/lint/test/deploy scripts — already wired up to the library's conventions. Requires `@screenly/edge-apps` `^1.2.0` or later. +- The generator only produces a basic app. Still check the closest match in the [Reference Apps](#reference-apps) section below and adapt from there for anything past that starting point — integrations/auth, Sentry error reporting, non-trivial settings, or a closer starting point for a complex UI. Note that the generator does not create `screenly_qc.yml` (an internal-only staging manifest) — copy one over from a reference app if your app needs one, and keep both manifests in sync. +- After scaffolding, register the app to populate a real `id` in `screenly.yml` (and `screenly_qc.yml`, if added): `screenly edge-app create --name --in-place`. - **Verify it boots** before building features: run `bun run dev`, `bun run lint`, and the tests. A scaffold that doesn't start is the first thing to fix. - **Consult Figma designs** before starting implementation. - Ensure the [Figma MCP server](https://mcp.figma.com/mcp) is set up in Claude Code. From bc4ce3a5b70235a1b3cfa148c6b8f9d762ffdb93 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Sun, 19 Jul 2026 12:30:23 -0700 Subject: [PATCH 2/4] docs: fix version constraint phrasing, drop premature registration step - use >=1.2.0 instead of the semantically inconsistent ^1.2.0 or later - drop the manual 'screenly edge-app create --in-place' registration step; standalone Edge App repos register/initialize apps via their own GitHub Actions workflow, not a manual command right after scaffolding --- .claude/skills/create-an-edge-app/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 75af6e0f4..80f844d4e 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -12,9 +12,8 @@ description: Use when scaffolding a new Screenly Edge App — covers the templat ```bash bunx @screenly/edge-apps create ``` - This produces a minimal, working app — manifest, `index.html`, `src/main.ts`, and the standard dev/build/lint/test/deploy scripts — already wired up to the library's conventions. Requires `@screenly/edge-apps` `^1.2.0` or later. + This produces a minimal, working app — manifest, `index.html`, `src/main.ts`, and the standard dev/build/lint/test/deploy scripts — already wired up to the library's conventions. Requires `@screenly/edge-apps` `>=1.2.0`. - The generator only produces a basic app. Still check the closest match in the [Reference Apps](#reference-apps) section below and adapt from there for anything past that starting point — integrations/auth, Sentry error reporting, non-trivial settings, or a closer starting point for a complex UI. Note that the generator does not create `screenly_qc.yml` (an internal-only staging manifest) — copy one over from a reference app if your app needs one, and keep both manifests in sync. -- After scaffolding, register the app to populate a real `id` in `screenly.yml` (and `screenly_qc.yml`, if added): `screenly edge-app create --name --in-place`. - **Verify it boots** before building features: run `bun run dev`, `bun run lint`, and the tests. A scaffold that doesn't start is the first thing to fix. - **Consult Figma designs** before starting implementation. - Ensure the [Figma MCP server](https://mcp.figma.com/mcp) is set up in Claude Code. From 7bed705c6be8ebd322754129d986c2278a531df3 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Sun, 19 Jul 2026 13:00:42 -0700 Subject: [PATCH 3/4] docs: add edge-apps-claude-config submodule step Standalone Edge App repos add the edge-apps-claude-config repo as a .claude submodule for Claude AI configuration; mention it right after the scaffold generator step. --- .claude/skills/create-an-edge-app/SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 80f844d4e..5f615c941 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -13,6 +13,10 @@ description: Use when scaffolding a new Screenly Edge App — covers the templat bunx @screenly/edge-apps create ``` This produces a minimal, working app — manifest, `index.html`, `src/main.ts`, and the standard dev/build/lint/test/deploy scripts — already wired up to the library's conventions. Requires `@screenly/edge-apps` `>=1.2.0`. +- After scaffolding — and before or alongside making further code changes — add and initialize the [`edge-apps-claude-config`](https://github.com/Screenly/edge-apps-claude-config) submodule for Claude AI configuration: + ```bash + git submodule add https://github.com/Screenly/edge-apps-claude-config .claude + ``` - The generator only produces a basic app. Still check the closest match in the [Reference Apps](#reference-apps) section below and adapt from there for anything past that starting point — integrations/auth, Sentry error reporting, non-trivial settings, or a closer starting point for a complex UI. Note that the generator does not create `screenly_qc.yml` (an internal-only staging manifest) — copy one over from a reference app if your app needs one, and keep both manifests in sync. - **Verify it boots** before building features: run `bun run dev`, `bun run lint`, and the tests. A scaffold that doesn't start is the first thing to fix. - **Consult Figma designs** before starting implementation. From d0f0a25737bb4089a8d1a04137c7e7409ae78cb2 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Sun, 19 Jul 2026 13:04:01 -0700 Subject: [PATCH 4/4] docs: scope the submodule step to standalone repos, add populate step - clarify the edge-apps-claude-config submodule step only applies to standalone Edge App repos, since this monorepo already has its own .claude/ - mention git submodule update --init for teammates cloning afterward --- .claude/skills/create-an-edge-app/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.claude/skills/create-an-edge-app/SKILL.md b/.claude/skills/create-an-edge-app/SKILL.md index 5f615c941..070abedd8 100644 --- a/.claude/skills/create-an-edge-app/SKILL.md +++ b/.claude/skills/create-an-edge-app/SKILL.md @@ -13,10 +13,11 @@ description: Use when scaffolding a new Screenly Edge App — covers the templat bunx @screenly/edge-apps create ``` This produces a minimal, working app — manifest, `index.html`, `src/main.ts`, and the standard dev/build/lint/test/deploy scripts — already wired up to the library's conventions. Requires `@screenly/edge-apps` `>=1.2.0`. -- After scaffolding — and before or alongside making further code changes — add and initialize the [`edge-apps-claude-config`](https://github.com/Screenly/edge-apps-claude-config) submodule for Claude AI configuration: +- If the new Edge App lives in its own standalone repo (not inside this monorepo, which already has its own `.claude/`), add and initialize the [`edge-apps-claude-config`](https://github.com/Screenly/edge-apps-claude-config) submodule for Claude AI configuration right after scaffolding, before or alongside making further code changes: ```bash git submodule add https://github.com/Screenly/edge-apps-claude-config .claude ``` + Teammates cloning the repo afterward need to populate it: `git submodule update --init` (or clone with `--recurse-submodules`). - The generator only produces a basic app. Still check the closest match in the [Reference Apps](#reference-apps) section below and adapt from there for anything past that starting point — integrations/auth, Sentry error reporting, non-trivial settings, or a closer starting point for a complex UI. Note that the generator does not create `screenly_qc.yml` (an internal-only staging manifest) — copy one over from a reference app if your app needs one, and keep both manifests in sync. - **Verify it boots** before building features: run `bun run dev`, `bun run lint`, and the tests. A scaffold that doesn't start is the first thing to fix. - **Consult Figma designs** before starting implementation.