@screenly/edge-apps 1.1.1 → 1.2.0

package/README.md

@@ -19,6 +19,49 @@ Or with Bun:
 bun add @screenly/edge-apps
 ```
 
+## Creating a New Edge App
+
+Scaffold a new Edge App without installing anything first:
+
+```bash
+npx @screenly/edge-apps create my-edge-app
+```
+
+Or with Bun:
+
+```bash
+bunx @screenly/edge-apps create my-edge-app
+```
+
+The package manager used to invoke the command is detected automatically, so
+the generated `package.json` scripts are wired up to match (`npm run ...` vs.
+`bun run ...`). This generates a minimal Edge App with a `screenly.yml`
+manifest, `index.html`, and a `src/main.ts` entry point wired up to this
+library.
+
+Pass options after the directory name, for example:
+
+```bash
+npx @screenly/edge-apps create my-edge-app --description "My Edge App" --author "Jane Doe"
+```
+
+| Option                 | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `--description <text>` | Description used in `package.json`, `screenly.yml`, and `README.md` |
+| `--author <text>`      | Author name added to `package.json`                                 |
+| `--pm <npm\|bun>`      | Force a package manager instead of auto-detecting it                |
+| `--force`              | Write into an existing, non-empty directory                         |
+| `--skip-install`       | Skip installing dependencies after scaffolding                      |
+
+> [!NOTE]
+> Running `edge-apps-scripts create` with no directory argument instead
+> replaces `{{APP_NAME}}`-style placeholders in the current project — this is
+> used by Edge App template repositories after cloning, and is unrelated to
+> scaffolding a brand new app.
+
+No test files are included — `test`/`test:unit` work out of the box on an
+empty suite; add your own under `src/` when you have something to test.
+
 ### Local Development Setup
 
 When developing Edge Apps locally using the library from this repository, you should link the package.

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@screenly/edge-apps",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
   "type": "module",
-  "sideEffects": ["**/*.css", "**/register.js", "**/buffer-shim.js"],
+  "sideEffects": [
+    "**/*.css",
+    "**/register.js",
+    "**/buffer-shim.js",
+    "**/components/**"
+  ],
   "engines": {
     "node": ">=20.6.0"
   },
@@ -103,7 +108,7 @@
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.0",
-    "vite": "^7.3.1",
+    "vite": "^8.1.2",
     "yaml": "^2.8.2"
   },
   "peerDependencies": {
@@ -118,9 +123,14 @@
     "@types/jsdom": "^28.0.0",
     "@types/node": "^25.4.0",
     "@types/sharp": "^0.32.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.9",
     "globals": "^13.24.0",
     "prettier": "^3.8.1",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.9"
+  },
+  "overrides": {
+    "@jsheaven/easybuild": {
+      "esbuild": "0.25.12"
+    }
   }
 }

package/scripts/cli.js

@@ -42,7 +42,7 @@ const commands = {
   },
   create: {
     description:
-      'Initialize a scaffolded Edge App (replaces template placeholders)',
+      'Scaffold a new Edge App (or replace template placeholders in the current project)',
     handler: createCommand,
   },
 }

package/scripts/create-scaffold.js

@@ -0,0 +1,234 @@
+import fs from 'fs'
+import path from 'path'
+import { spawnSync } from 'child_process'
+import { fileURLToPath } from 'url'
+import {
+  toKebabCase,
+  toTitleCase,
+  walkTextFiles,
+  replaceInFile,
+} from './template-utils.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const libraryRoot = path.resolve(__dirname, '..')
+const templateRoot = path.resolve(__dirname, 'create-template')
+const libraryPkg = JSON.parse(
+  fs.readFileSync(path.join(libraryRoot, 'package.json'), 'utf-8'),
+)
+
+const NPM_RUN_ALL2_VERSION = '^8.0.4'
+const TYPES_BUN_VERSION = '^1.3.13'
+const BUN_TYPES_VERSION = '^1.3.13'
+
+const VALUE_FLAGS = new Set(['--pm', '--description', '--author'])
+const BOOLEAN_FLAGS = new Set(['--force', '--skip-install'])
+
+export function parseCreateArgs(args) {
+  const options = {
+    pm: null,
+    description: null,
+    author: null,
+    force: false,
+    skipInstall: false,
+  }
+  const positional = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (VALUE_FLAGS.has(arg)) {
+      const value = args[i + 1]
+      if (value === undefined || value.startsWith('-')) {
+        return { error: `Missing value for ${arg}` }
+      }
+      i++
+      if (arg === '--pm') options.pm = value
+      else if (arg === '--description') options.description = value
+      else options.author = value
+    } else if (BOOLEAN_FLAGS.has(arg)) {
+      if (arg === '--force') options.force = true
+      else options.skipInstall = true
+    } else if (arg.startsWith('-')) {
+      return { error: `Unknown option: ${arg}` }
+    } else {
+      positional.push(arg)
+    }
+  }
+
+  if (positional.length > 1) {
+    return {
+      error: `Expected a single directory argument, got: ${positional.join(', ')}`,
+    }
+  }
+
+  return { directory: positional[0], options }
+}
+
+function validateDescription(description) {
+  if (description !== null && /[\r\n]/.test(description)) {
+    return 'Description cannot contain line breaks.'
+  }
+  return null
+}
+
+function detectPackageManager(explicit) {
+  if (explicit) {
+    if (explicit !== 'npm' && explicit !== 'bun') {
+      console.error(
+        `Unsupported package manager: ${explicit}. Use "npm" or "bun".`,
+      )
+      return null
+    }
+    return explicit
+  }
+
+  const userAgent = process.env.npm_config_user_agent || ''
+  return userAgent.startsWith('bun') ? 'bun' : 'npm'
+}
+
+function finalizePackageJson(destination, pm) {
+  const pkgPath = path.join(destination, 'package.json')
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    '@screenly/edge-apps': `^${libraryPkg.version}`,
+    typescript: libraryPkg.dependencies.typescript,
+    prettier: libraryPkg.devDependencies.prettier,
+    '@types/node': libraryPkg.devDependencies['@types/node'],
+    'npm-run-all2': NPM_RUN_ALL2_VERSION,
+    '@playwright/test': libraryPkg.peerDependencies['@playwright/test'],
+  }
+
+  if (pm === 'bun') {
+    pkg.scripts.test = 'bun test --pass-with-no-tests src/'
+    pkg.devDependencies['@types/bun'] = TYPES_BUN_VERSION
+    pkg.devDependencies['bun-types'] = BUN_TYPES_VERSION
+    pkg.devDependencies.jsdom = libraryPkg.dependencies.jsdom
+    pkg.devDependencies['@types/jsdom'] =
+      libraryPkg.devDependencies['@types/jsdom']
+  } else {
+    pkg.scripts.test = 'vitest run --passWithNoTests'
+    pkg.devDependencies.vitest = libraryPkg.devDependencies.vitest
+    pkg.devDependencies.jsdom = libraryPkg.dependencies.jsdom
+  }
+  pkg.scripts['test:unit'] = pkg.scripts.test
+
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8')
+}
+
+function installDependencies(destination, pm) {
+  console.log(`\nInstalling dependencies with ${pm}...`)
+  const result = spawnSync(pm, ['install'], {
+    cwd: destination,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+  if (result.status !== 0) {
+    console.warn(
+      `\n${pm} install failed. Run it manually inside ${destination}.`,
+    )
+  }
+}
+
+function printScaffoldNextSteps(destination, appName, pm) {
+  const relativePath = path.relative(process.cwd(), destination) || '.'
+  const runCommand = pm === 'bun' ? 'bun run' : 'npm run'
+  const installCommand = pm === 'bun' ? 'bun install' : 'npm install'
+  const needsInstall = !fs.existsSync(path.join(destination, 'node_modules'))
+
+  const steps = [`cd "${relativePath}"`]
+  if (needsInstall) steps.push(installCommand)
+  steps.push(
+    `Register the app to get an id for screenly.yml:\n       screenly edge-app create --name ${appName} --in-place`,
+    `Start the dev server:\n       ${runCommand} dev`,
+    `Deploy when ready:\n       ${runCommand} deploy`,
+  )
+
+  console.log(`
+Done! Your Edge App is ready.
+
+Next steps:
+${steps.map((step, index) => `  ${index + 1}. ${step}`).join('\n')}
+`)
+}
+
+export function scaffoldNewApp(directory, options) {
+  const pm = detectPackageManager(options.pm)
+  if (!pm) {
+    process.exitCode = 1
+    return
+  }
+
+  const descriptionError = validateDescription(options.description)
+  if (descriptionError) {
+    console.error(descriptionError)
+    process.exitCode = 1
+    return
+  }
+
+  const destination = path.resolve(process.cwd(), directory)
+
+  if (fs.existsSync(destination)) {
+    if (!fs.statSync(destination).isDirectory()) {
+      console.error(`"${directory}" already exists and is not a directory.`)
+      process.exitCode = 1
+      return
+    }
+    const isEmpty = fs.readdirSync(destination).length === 0
+    if (!isEmpty && !options.force) {
+      console.error(
+        `Directory "${directory}" already exists and is not empty. Use --force to write into it anyway.`,
+      )
+      process.exitCode = 1
+      return
+    }
+  } else {
+    fs.mkdirSync(destination, { recursive: true })
+  }
+
+  const appName = toKebabCase(path.basename(destination))
+  const appTitle = toTitleCase(appName)
+  const appDescription =
+    options.description ?? `${appTitle} - Screenly Edge App`
+
+  console.log(`\nScaffolding a new Edge App in ${destination}`)
+
+  fs.cpSync(templateRoot, destination, { recursive: true })
+  fs.copyFileSync(
+    path.join(destination, '_gitignore'),
+    path.join(destination, '.gitignore'),
+  )
+  fs.rmSync(path.join(destination, '_gitignore'))
+
+  const replacements = {
+    '{{APP_NAME}}': appName,
+    '{{APP_TITLE}}': appTitle,
+    '{{APP_DESCRIPTION}}': appDescription,
+    '{{APP_DESCRIPTION_JSON}}': JSON.stringify(appDescription).slice(1, -1),
+    '{{APP_DESCRIPTION_YAML}}': appDescription.replace(/'/g, "''"),
+    '{{PM_RUN}}': pm === 'bun' ? 'bun run' : 'npm run',
+    '{{PM_INSTALL}}': pm === 'bun' ? 'bun install' : 'npm install',
+  }
+  for (const filePath of walkTextFiles(destination)) {
+    replaceInFile(filePath, replacements)
+  }
+
+  finalizePackageJson(destination, pm)
+
+  if (options.author) {
+    const pkgPath = path.join(destination, 'package.json')
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    pkg.author = options.author
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8')
+  }
+
+  if (pm === 'bun') {
+    fs.rmSync(path.join(destination, 'vitest.config.ts'), { force: true })
+  }
+
+  if (!options.skipInstall) {
+    installDependencies(destination, pm)
+  }
+
+  printScaffoldNextSteps(destination, appName, pm)
+}

package/scripts/create-template/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 80
+}

package/scripts/create-template/README.md

@@ -0,0 +1,43 @@
+# {{APP_TITLE}}
+
+{{APP_DESCRIPTION}}
+
+## Getting Started
+
+Install dependencies:
+
+```bash
+{{PM_INSTALL}}
+```
+
+## Development
+
+```bash
+{{PM_RUN}} dev
+```
+
+## Build
+
+```bash
+{{PM_RUN}} build
+```
+
+## Deployment
+
+```bash
+screenly edge-app create --name {{APP_NAME}} --in-place
+{{PM_RUN}} deploy
+screenly edge-app instance create
+```
+
+## Configuration
+
+| Setting   | Description                     | Required | Default            |
+| --------- | ------------------------------- | -------- | ------------------ |
+| `message` | The message displayed on screen | No       | `Hello, Screenly!` |
+
+## Screenshots
+
+```bash
+{{PM_RUN}} screenshots
+```

package/scripts/create-template/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+mock-data.yml

package/scripts/create-template/e2e/screenshots.spec.ts

@@ -0,0 +1,33 @@
+import { test } from '@playwright/test'
+import {
+  createMockScreenlyForScreenshots,
+  getScreenshotsDir,
+  RESOLUTIONS,
+  setupClockMock,
+  setupScreenlyJsMock,
+} from '@screenly/edge-apps/test/screenshots'
+import path from 'path'
+
+const { screenlyJsContent } = createMockScreenlyForScreenshots()
+
+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 setupClockMock(page)
+    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()
+  })
+}

package/scripts/create-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}} - Screenly Edge App</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 show-date></app-header>
+        <main class="content">
+          <h1 id="message"></h1>
+        </main>
+      </div>
+    </auto-scaler>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/scripts/create-template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "description": "{{APP_DESCRIPTION_JSON}}",
+  "type": "module",
+  "scripts": {
+    "prebuild": "{{PM_RUN}} type-check",
+    "generate-mock-data": "screenly edge-app run --generate-mock-data",
+    "predev": "{{PM_RUN}} generate-mock-data",
+    "cors-proxy-server": "edge-apps-scripts cors-proxy",
+    "dev": "run-p cors-proxy-server edge-apps-dev",
+    "edge-apps-dev": "edge-apps-scripts dev",
+    "build": "edge-apps-scripts build",
+    "build:dev": "edge-apps-scripts build:dev",
+    "build:prod": "edge-apps-scripts build",
+    "test": "",
+    "test:unit": "",
+    "lint": "edge-apps-scripts lint --fix",
+    "format": "prettier --write src/ README.md index.html",
+    "format:check": "prettier --check src/ README.md index.html",
+    "deploy": "{{PM_RUN}} build && screenly edge-app deploy --path=dist/",
+    "type-check": "edge-apps-scripts type-check",
+    "screenshots": "edge-apps-scripts screenshots"
+  },
+  "prettier": "./.prettierrc.json",
+  "devDependencies": {}
+}

package/scripts/create-template/screenly.yml

@@ -0,0 +1,17 @@
+---
+syntax: manifest_v1
+description: '{{APP_DESCRIPTION_YAML}}'
+ready_signal: true
+settings:
+  message:
+    type: string
+    default_value: 'Hello, Screenly!'
+    title: Message
+    optional: true
+    help_text: The message displayed on screen.
+  sentry_dsn:
+    type: secret
+    title: Sentry Client Key
+    optional: true
+    help_text: Sentry Client Key from Sentry SDK for error capturing.
+    is_global: true

package/scripts/create-template/src/main.ts

@@ -0,0 +1,18 @@
+import './style.css'
+import '@screenly/edge-apps/components'
+import {
+  getSettingWithDefault,
+  setupErrorHandling,
+  setupTheme,
+  signalReady,
+} from '@screenly/edge-apps'
+
+document.addEventListener('DOMContentLoaded', () => {
+  setupErrorHandling()
+  setupTheme()
+
+  const message = getSettingWithDefault<string>('message', 'Hello, Screenly!')
+  document.getElementById('message')!.textContent = message
+
+  signalReady()
+})

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

@@ -0,0 +1,30 @@
+@import '@screenly/edge-apps/styles';
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+  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);
+}

package/scripts/create-template/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@screenly/edge-apps/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/scripts/create-template/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+  },
+})

package/scripts/create.js

@@ -1,60 +1,9 @@
 import fs from 'fs'
 import path from 'path'
+import { toTitleCase, walkTextFiles, replaceInFile } from './template-utils.js'
+import { parseCreateArgs, scaffoldNewApp } from './create-scaffold.js'
 
-const TEXT_EXTENSIONS = new Set([
-  '.ts',
-  '.tsx',
-  '.js',
-  '.jsx',
-  '.html',
-  '.css',
-  '.scss',
-  '.json',
-  '.yml',
-  '.yaml',
-  '.md',
-  '.txt',
-  '.svg',
-  '.gitignore',
-  '.ignore',
-])
-
-const SKIP_DIRS = new Set(['node_modules', 'dist', '.git'])
-
-function toTitleCase(kebab) {
-  return kebab
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ')
-}
-
-function walkTextFiles(dir) {
-  const results = []
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path.join(dir, entry.name)
-    if (entry.isDirectory()) {
-      if (!SKIP_DIRS.has(entry.name)) results.push(...walkTextFiles(fullPath))
-    } else if (
-      entry.isFile() &&
-      (TEXT_EXTENSIONS.has(path.extname(entry.name)) ||
-        TEXT_EXTENSIONS.has(entry.name))
-    ) {
-      results.push(fullPath)
-    }
-  }
-  return results
-}
-
-function replaceInFile(filePath, replacements) {
-  const original = fs.readFileSync(filePath, 'utf-8')
-  const updated = Object.entries(replacements).reduce(
-    (src, [placeholder, value]) => src.replaceAll(placeholder, value),
-    original,
-  )
-  if (updated !== original) fs.writeFileSync(filePath, updated, 'utf-8')
-}
-
-export async function createCommand(_args) {
+function initializeExistingProject() {
   const projectRoot = process.cwd()
   const pkgPath = path.join(projectRoot, 'package.json')
 
@@ -64,7 +13,9 @@ export async function createCommand(_args) {
   } catch (error) {
     console.error(
       `Failed to read or parse package.json at ${pkgPath}. ` +
-        'Make sure you are running this command from an Edge App project root.',
+        'Make sure you are running this command from an Edge App project root, ' +
+        'or pass a directory name to scaffold a new Edge App: ' +
+        'npx @screenly/edge-apps create <directory> (or bunx @screenly/edge-apps create <directory>)',
     )
     if (error instanceof Error && error.message) {
       console.error(`Details: ${error.message}`)
@@ -93,7 +44,7 @@ export async function createCommand(_args) {
     replaceInFile(filePath, replacements)
   }
 
-  const updatedPkg = { ...pkg }
+  const updatedPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
   delete updatedPkg['bun-create']
   fs.writeFileSync(pkgPath, JSON.stringify(updatedPkg, null, 2) + '\n', 'utf-8')
 
@@ -113,3 +64,38 @@ Next steps:
        npm run deploy
 `)
 }
+
+function hasScaffoldOnlyOptions(options) {
+  return (
+    options.description !== null ||
+    options.author !== null ||
+    options.pm !== null ||
+    options.force ||
+    options.skipInstall
+  )
+}
+
+export async function createCommand(args) {
+  const { directory, options, error } = parseCreateArgs(args)
+
+  if (error) {
+    console.error(error)
+    process.exitCode = 1
+    return
+  }
+
+  if (!directory && hasScaffoldOnlyOptions(options)) {
+    console.error(
+      'Options like --description/--author/--pm/--force/--skip-install only apply ' +
+        'when scaffolding a new app: npx @screenly/edge-apps create <directory>',
+    )
+    process.exitCode = 1
+    return
+  }
+
+  if (directory) {
+    scaffoldNewApp(directory, options)
+  } else {
+    initializeExistingProject()
+  }
+}

package/scripts/template-utils.js

@@ -0,0 +1,65 @@
+import fs from 'fs'
+import path from 'path'
+
+const TEXT_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.html',
+  '.css',
+  '.scss',
+  '.json',
+  '.yml',
+  '.yaml',
+  '.md',
+  '.txt',
+  '.svg',
+  '.gitignore',
+  '.ignore',
+  '_gitignore',
+])
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git'])
+
+export function toTitleCase(kebab) {
+  return kebab
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+export function toKebabCase(name) {
+  const kebab = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return kebab || 'my-edge-app'
+}
+
+export function walkTextFiles(dir) {
+  const results = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) results.push(...walkTextFiles(fullPath))
+    } else if (
+      entry.isFile() &&
+      (TEXT_EXTENSIONS.has(path.extname(entry.name)) ||
+        TEXT_EXTENSIONS.has(entry.name))
+    ) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+
+export function replaceInFile(filePath, replacements) {
+  const original = fs.readFileSync(filePath, 'utf-8')
+  const updated = Object.entries(replacements).reduce(
+    (src, [placeholder, value]) => src.replaceAll(placeholder, value),
+    original,
+  )
+  if (updated !== original) fs.writeFileSync(filePath, updated, 'utf-8')
+}