From 6952c4b65a9ae7a7dcf47f19fa2b1e3cd829c725 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Fri, 24 Jul 2026 16:12:30 -0700 Subject: [PATCH 1/6] feat(create-template): enable Tailwind CSS for scaffolded Edge Apps - Import tailwindcss in the scaffold stylesheet, using the @tailwindcss/vite plugin already wired into vite.config.ts - Replace scaffold's custom flex/layout CSS with Tailwind utility classes to demonstrate usage - Document Tailwind support and the auto-scaler h-full/w-full vs h-screen/w-screen gotcha in both READMEs --- README.md | 19 +++++++++++++++++++ scripts/create-template/README.md | 2 ++ scripts/create-template/index.html | 6 +++--- scripts/create-template/src/style.css | 15 +-------------- 4 files changed, 25 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index f74bb09..2725f96 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,25 @@ signalReady() 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 +@import 'tailwindcss'; +``` + +Then use utility classes directly in your markup instead of writing custom CSS: + +```html +
+

Hello, Screenly!

+
+``` + +> [!IMPORTANT] +> Inside ``, use `h-full`/`w-full` instead of `h-screen`/`w-screen`. `` 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 `` uses the same way. + ## 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. diff --git a/scripts/create-template/README.md b/scripts/create-template/README.md index f0812c4..728d011 100644 --- a/scripts/create-template/README.md +++ b/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 `@import 'tailwindcss';` in `src/style.css`. Inside ``, 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 diff --git a/scripts/create-template/index.html b/scripts/create-template/index.html index 32990d9..919f3fd 100644 --- a/scripts/create-template/index.html +++ b/scripts/create-template/index.html @@ -12,10 +12,10 @@ reference-height="1080" orientation="auto" > -
+
-
-

+
+

diff --git a/scripts/create-template/src/style.css b/scripts/create-template/src/style.css index 035e3ef..79fb940 100644 --- a/scripts/create-template/src/style.css +++ b/scripts/create-template/src/style.css @@ -1,3 +1,4 @@ +@import 'tailwindcss'; @import '@screenly/edge-apps/styles'; * { @@ -11,20 +12,6 @@ body { font-family: 'Inter', system-ui, sans-serif; } -#app { - display: flex; - flex-direction: column; - width: 100%; - height: 100%; -} - -.content { - flex: 1; - display: flex; - align-items: center; - justify-content: center; -} - #message { color: var(--theme-color-primary, #972eff); } From fac7aa81e0c0a0353e4e4a4b1c13d68c0b57831f Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 27 Jul 2026 08:34:52 -0700 Subject: [PATCH 2/6] chore(release): bump version to 1.3.0 - reflects Tailwind CSS support added in this branch --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 034b5cf..d3314c5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@screenly/edge-apps", - "version": "1.2.1", + "version": "1.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@screenly/edge-apps", - "version": "1.2.1", + "version": "1.3.0", "license": "MIT", "dependencies": { "@eslint/js": "^10.0.1", diff --git a/package.json b/package.json index ed38bdd..7b6797b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@screenly/edge-apps", - "version": "1.2.1", + "version": "1.3.0", "description": "A TypeScript library for interfacing with Screenly Edge Apps API", "type": "module", "sideEffects": [ From dfe578290543c976813faaaf39eb6bb26465fc39 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 27 Jul 2026 10:36:53 -0700 Subject: [PATCH 3/6] fix(create-template): skip Tailwind Preflight in scaffolded styles - import tailwindcss/theme.css and utilities.css directly instead of the full tailwindcss package, avoiding Preflight's universal border/margin/ padding reset which silently overrides shadow-DOM :host styling on components like - document the same guidance and warning in README.md --- README.md | 6 +++++- scripts/create-template/src/style.css | 8 +++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2725f96..1c96659 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,8 @@ This library includes reusable web components for building consistent Edge Apps. 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 -@import 'tailwindcss'; +@import 'tailwindcss/theme.css' layer(theme); +@import 'tailwindcss/utilities.css' layer(utilities); ``` Then use utility classes directly in your markup instead of writing custom CSS: @@ -169,6 +170,9 @@ Then use utility classes directly in your markup instead of writing custom CSS: > [!IMPORTANT] > Inside ``, use `h-full`/`w-full` instead of `h-screen`/`w-screen`. `` 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 `` 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 `` 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. diff --git a/scripts/create-template/src/style.css b/scripts/create-template/src/style.css index 79fb940..2d028b7 100644 --- a/scripts/create-template/src/style.css +++ b/scripts/create-template/src/style.css @@ -1,4 +1,10 @@ -@import 'tailwindcss'; +/* Skip Tailwind's preflight: it resets `border`/`margin`/`padding` on every + element via a universal selector, including custom-element hosts like + , which style themselves through `:host` in their own shadow + DOM. That reset silently overrides their styling. Import just the theme + and utilities instead. */ +@import 'tailwindcss/theme.css' layer(theme); +@import 'tailwindcss/utilities.css' layer(utilities); @import '@screenly/edge-apps/styles'; * { From 335af4f93119ae7520b25ba768144c6e00654bb9 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 27 Jul 2026 10:42:47 -0700 Subject: [PATCH 4/6] docs(create-template): fix stale Tailwind import reference in README - update the scaffold README to match the actual theme/utilities imports used in src/style.css, instead of the deprecated full 'tailwindcss' import - addresses Copilot review feedback on PR #63 --- scripts/create-template/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/create-template/README.md b/scripts/create-template/README.md index 728d011..253d6b4 100644 --- a/scripts/create-template/README.md +++ b/scripts/create-template/README.md @@ -16,7 +16,7 @@ Install dependencies: {{PM_RUN}} dev ``` -Styling uses [Tailwind CSS](https://tailwindcss.com/) utility classes, enabled via `@import 'tailwindcss';` in `src/style.css`. Inside ``, 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. +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 ``, 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 From 808ff4b43e167c08bfea9fba9d8d788abe004fba Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 27 Jul 2026 10:53:46 -0700 Subject: [PATCH 5/6] fix(create-template): put Screenly base styles in a cascade layer - declare an explicit theme/base/utilities layer order and import @screenly/edge-apps/styles into the base layer, so Tailwind utility classes always win the cascade regardless of selector specificity - unlayered CSS otherwise beats layered CSS per the Cascade Layers spec, letting @screenly/edge-apps/styles's base rules (e.g. its user-select: none reset) silently override Tailwind utilities - document the same layered setup in README.md - addresses Copilot review feedback on PR #63 --- README.md | 6 ++++++ scripts/create-template/src/style.css | 31 ++++++++++++++++----------- 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1c96659..f4b8e54 100644 --- a/README.md +++ b/README.md @@ -155,10 +155,16 @@ This library includes reusable web components for building consistent Edge Apps. 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 diff --git a/scripts/create-template/src/style.css b/scripts/create-template/src/style.css index 2d028b7..c743f48 100644 --- a/scripts/create-template/src/style.css +++ b/scripts/create-template/src/style.css @@ -3,21 +3,28 @@ , which style themselves through `:host` in their own shadow DOM. That reset silently overrides their styling. Import just the theme and utilities instead. */ +@layer theme, base, utilities; + @import 'tailwindcss/theme.css' layer(theme); +/* @screenly/edge-apps/styles and the rules below go in the `base` layer so + Tailwind utilities (declared after `base` above) always win the cascade, + regardless of selector specificity. */ +@import '@screenly/edge-apps/styles' layer(base); @import 'tailwindcss/utilities.css' layer(utilities); -@import '@screenly/edge-apps/styles'; -* { - box-sizing: border-box; -} +@layer base { + * { + box-sizing: border-box; + } -body { - margin: 0; - padding: 0; - overflow: hidden; - font-family: 'Inter', system-ui, sans-serif; -} + 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); + } } From af500a066d074b6936f9620529400456ec8ff814 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Tue, 28 Jul 2026 07:30:53 -0700 Subject: [PATCH 6/6] chore: remove comments from the template's CSS file --- scripts/create-template/src/style.css | 8 -------- 1 file changed, 8 deletions(-) diff --git a/scripts/create-template/src/style.css b/scripts/create-template/src/style.css index c743f48..e79be54 100644 --- a/scripts/create-template/src/style.css +++ b/scripts/create-template/src/style.css @@ -1,14 +1,6 @@ -/* Skip Tailwind's preflight: it resets `border`/`margin`/`padding` on every - element via a universal selector, including custom-element hosts like - , which style themselves through `:host` in their own shadow - DOM. That reset silently overrides their styling. Import just the theme - and utilities instead. */ @layer theme, base, utilities; @import 'tailwindcss/theme.css' layer(theme); -/* @screenly/edge-apps/styles and the rules below go in the `base` layer so - Tailwind utilities (declared after `base` above) always win the cascade, - regardless of selector specificity. */ @import '@screenly/edge-apps/styles' layer(base); @import 'tailwindcss/utilities.css' layer(utilities);