Merge branch 'master' into dependabot/bun/edge-apps/asset-metadata/bun-2f8a279dda

Author: nicomiguelino

.claude/skills/create-an-edge-app/SKILL.md

@@ -7,56 +7,40 @@ description: The recommended way to create an Edge App
 
 ## When Creating an Edge App
 
-- Create a new directory for a new Edge App inside the `edge-apps/` directory.
-  - The directory name should follow the `kebab-case` naming convention.
+- Scaffold the new Edge App using the `bun create` template from inside the `edge-apps/` directory:
+  ```bash
+  bun create edge-app-template --no-git <app-name>
+  ```
+  - The app name should follow the `kebab-case` naming convention.
+- After scaffolding, add an `id` field to `screenly.yml` and `screenly_qc.yml` before running `bun run dev`.
 - **Consult Figma designs** before starting implementation.
   - Ensure the [Figma MCP server](https://mcp.figma.com/mcp) is set up in Claude Code.
   - Use the Figma MCP server to access design specifications, mockups, and UI requirements.
   - Extract design tokens such as colors, spacing, typography, and component specifications from Figma.
   - Ensure the implementation matches the approved designs in Figma before proceeding with development.
 
-## Directory Structure
+## Reference Apps
 
-The new Edge App directory structure should closely resemble that of the following Edge Apps:
+For reference on more complex implementations, consult:
 
-- QR Code (`edge-apps/qr-code/`)
-- Menu Board (`edge-apps/menu-board/`)
-- Grafana (`edge-apps/grafana/`)
-- CAP Alerting (`edge-apps/cap-alerting/`)
+- QR Code (`edge-apps/qr-code/`) — simple, low-footprint example
+- Menu Board (`edge-apps/menu-board/`) — more complex layout
+- CAP Alerting (`edge-apps/cap-alerting/`) — advanced settings and data fetching
 
-These Edge Apps heavily rely on the Edge Apps library, which lives inside the `edge-apps/edge-apps-library/` directory.
-
-- Most of the scripts inside the `package.json` of each of these apps execute the `edge-apps-scripts` command.
-- All of these apps depend on the `@screenly/edge-apps` library, which maps to `workspace:../edge-apps-library`.
-- `edge-apps/[new-edge-app]/src/main.ts` is a required file.
-  - Running `bun run build` inside `edge-apps/[new-edge-app]` will run `edge-apps-scripts build`, which is very opinionated.
-
-Refer to `edge-apps/qr-code/` as a complete working template to understand the full directory structure and configuration.
-
-- While it still uses the `@screenly/edge-apps` library, it features a simpler implementation with a lower code footprint compared to the other aforementioned Edge Apps, making it an excellent starting point for new projects.
-- The library abstracts much of the complexity, allowing developers to focus on core functionality with minimal boilerplate.
+All apps depend on the `@screenly/edge-apps` library (`workspace:../edge-apps-library`) and use `edge-apps-scripts` for tooling.
 
 ### About the Manifest Files
 
-The new app should have the following manifest files:
-
-- `screenly.yml`
-- `screenly_qc.yml`
-
-See `edge-apps/qr-code/screenly.yml` for a working example. More information about the manifest files can be found in the [Edge Apps documentation in the `Screenly/cli` repository](https://raw.githubusercontent.com/Screenly/cli/refs/heads/master/docs/EdgeApps.md).
-
-When creating the manifest files, ensure to:
-
-- Omit the `id` field, as it will be added later when the new app gets deployed.
+- Add any app-specific settings under the `settings` key, sorted alphabetically.
+- More information about manifest files can be found in the [Edge Apps documentation in the `Screenly/cli` repository](https://raw.githubusercontent.com/Screenly/cli/refs/heads/master/docs/EdgeApps.md).
 
 ### About `index.html`
 
-The `index.html` file should follow these best practices:
 - Organize HTML code into templates and Web Components as the app grows in complexity.
 - Use HTML content templates first for simpler structures.
 - Consider using Web Components for more complex UI components that require encapsulation and reusability.
 
 ### About `README.md`
 
 - Include instructions on how to create, build, test, format, lint, and deploy the app.
-- Do not add details like the directory structure, as the code frequently changes.
+- Do not add details like the directory structure, as the code frequently changes.

.prettierignore

@@ -1,4 +1,5 @@
 **/*.min.js
+edge-apps/.bun-create/
 edge-apps/cap-alerting/
 edge-apps/clock/
 edge-apps/edge-apps-library/

README.md

@@ -35,6 +35,16 @@ If you are not familiar with Edge Apps, we suggest you review our [developer doc
 - [Weather App](https://github.com/Screenly/Playground/tree/master/edge-apps/weather) - A simple weather app.
 - [Welcome App](https://github.com/Screenly/Playground/tree/master/edge-apps/welcome-app) - A customizable welcome screen app.
 
+### Creating a New Edge App
+
+To scaffold a new Edge App, run the following from the `edge-apps/` directory:
+
+```bash
+bun create edge-app-template --no-git <your-app-name>
+```
+
+This generates a new app with TypeScript, the Screenly design system, manifest files, and all standard scripts pre-configured. See [`edge-apps/README.md`](/edge-apps/README.md) for full details.
+
 ### TypeScript Library (New)
 
 The Playground also offers an Edge Apps library that contains utilities for building Edge Apps including helper functions.

edge-apps/.bun-create/edge-app-template/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

edge-apps/.bun-create/edge-app-template/.ignore

@@ -0,0 +1 @@
+node_modules/

edge-apps/.bun-create/edge-app-template/README.md

@@ -0,0 +1,51 @@
+# {{APP_TITLE}}
+
+## Getting Started
+
+```bash
+bun install
+```
+
+## Deployment
+
+Create and deploy the Edge App:
+
+```bash
+screenly edge-app create --name {{APP_NAME}} --in-place
+bun run deploy
+screenly edge-app instance create
+```
+
+## Configuration
+
+The app accepts the following settings via `screenly.yml`:
+
+| Setting             | Description                                                                                                                                                   | Type     | Default         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------- |
+| `display_errors`    | Display errors on screen for debugging purposes                                                                                                               | optional | `false`         |
+| `message`           | The message to display on screen                                                                                                                              | required | `Hello, World!` |
+| `override_locale`   | Override the default locale with a supported language code                                                                                                    | optional | `en`            |
+| `override_timezone` | Override the default timezone with a supported timezone identifier (e.g., `Europe/London`, `America/New_York`). Defaults to the system timezone if left blank | optional | -               |
+
+## Development
+
+```bash
+bun install      # Install dependencies
+bun run dev      # Start development server
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+## Screenshots
+
+Generate screenshots at all supported resolutions:
+
+```bash
+bun run screenshots
+```
+
+Screenshots are saved to the `screenshots/` directory.

edge-apps/.bun-create/edge-app-template/e2e/screenshots.spec.ts

@@ -0,0 +1,39 @@
+import { test } from '@playwright/test'
+import {
+  createMockScreenlyForScreenshots,
+  getScreenshotsDir,
+  RESOLUTIONS,
+  setupScreenlyJsMock,
+} from '@screenly/edge-apps/test/screenshots'
+import path from 'path'
+
+const { screenlyJsContent } = createMockScreenlyForScreenshots(
+  { coordinates: [40.7128, -74.006], location: 'New York, NY' },
+  {
+    display_errors: 'false',
+    message: 'Hello, World!',
+    override_locale: 'en',
+    override_timezone: 'America/New_York',
+  },
+)
+
+for (const { width, height } of RESOLUTIONS) {
+  test(`screenshot ${width}x${height}`, async ({ browser }) => {
+    const screenshotsDir = getScreenshotsDir()
+
+    const context = await browser.newContext({ viewport: { width, height } })
+    const page = await context.newPage()
+
+    await setupScreenlyJsMock(page, screenlyJsContent)
+
+    await page.goto('/')
+    await page.waitForLoadState('networkidle')
+
+    await page.screenshot({
+      path: path.join(screenshotsDir, `${width}x${height}.png`),
+      fullPage: false,
+    })
+
+    await context.close()
+  })
+}

edge-apps/.bun-create/edge-app-template/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+    <script src="screenly.js?version=1"></script>
+  </head>
+  <body>
+    <auto-scaler
+      reference-width="1920"
+      reference-height="1080"
+      orientation="auto"
+    >
+      <div id="app">
+        <app-header class="header" show-date></app-header>
+        <main class="content">
+          <p id="message"></p>
+        </main>
+      </div>
+    </auto-scaler>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

edge-apps/.bun-create/edge-app-template/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "edge-app-template",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "prebuild": "bun run type-check",
+    "generate-mock-data": "screenly edge-app run --generate-mock-data",
+    "predev": "bun run generate-mock-data",
+    "dev": "edge-apps-scripts dev",
+    "build": "edge-apps-scripts build",
+    "build:dev": "edge-apps-scripts build:dev",
+    "build:prod": "edge-apps-scripts build",
+    "test": "bun test --pass-with-no-tests src/",
+    "test:unit": "bun test --pass-with-no-tests src/",
+    "lint": "edge-apps-scripts lint --fix",
+    "format": "prettier --write src/ README.md index.html",
+    "format:check": "prettier --check src/ README.md index.html",
+    "deploy": "bun run build && screenly edge-app deploy --path=dist/",
+    "type-check": "edge-apps-scripts type-check",
+    "screenshots": "edge-apps-scripts screenshots",
+    "prepare": "cd ../edge-apps-library && bun install && bun run build"
+  },
+  "prettier": "../edge-apps-library/.prettierrc.json",
+  "devDependencies": {
+    "@playwright/test": "^1.58.0",
+    "@screenly/edge-apps": "workspace:../edge-apps-library",
+    "@types/bun": "^1.3.9",
+    "@types/jsdom": "^27.0.0",
+    "bun-types": "^1.3.9",
+    "jsdom": "^28.1.0",
+    "npm-run-all2": "^8.0.4",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3"
+  },
+  "bun-create": {
+    "postinstall": "edge-apps-scripts create"
+  }
+}

edge-apps/.bun-create/edge-app-template/screenly.yml

@@ -0,0 +1,39 @@
+---
+syntax: manifest_v1
+description: {{APP_DESCRIPTION}}
+icon: https://playground.srly.io/edge-apps/{{APP_NAME}}/static/img/icon.svg
+author: Screenly, Inc.
+ready_signal: true
+settings:
+  display_errors:
+    type: string
+    default_value: 'false'
+    title: Display Errors
+    optional: true
+    help_text:
+      properties:
+        advanced: true
+        help_text: For debugging purposes to display errors on the screen.
+        type: boolean
+      schema_version: 1
+  message:
+    type: string
+    default_value: Hello, World!
+    title: Message
+    optional: false
+    help_text: |
+      The message to display on screen.
+  override_locale:
+    type: string
+    default_value: en
+    title: Override Locale
+    optional: true
+    help_text: |
+      Override the default locale with a supported language code (e.g., en, fr, de). Defaults to English if not specified.
+  override_timezone:
+    type: string
+    default_value: ''
+    title: Override Timezone
+    optional: true
+    help_text: |
+      Override the default timezone with a supported timezone identifier (e.g., Europe/London, America/New_York). Defaults to the system timezone if left blank.