@inglorious/create-app 1.1.1 → 1.2.0

package/bin/lib/features.js

@@ -0,0 +1,142 @@
+// The choices create-app offers for lit-html apps, and what each one brings.
+
+export const THEMES = {
+  inglorious: { title: "Inglorious", description: "Neon, videogame-inspired" },
+  material: { title: "Material", description: "Material Design inspired" },
+  bootstrap: { title: "Bootstrap", description: "Bootstrap inspired" },
+}
+
+// Icon sets from Iconify: one module per icon, so only the icons an app
+// imports are bundled. `nav` names the icons for the two example pages,
+// `showcase` the one shown on the home page.
+export const ICON_PACKS = {
+  material: {
+    title: "Material Symbols",
+    packages: { "@iconify-icons/material-symbols": "^2.0.6" },
+    nav: {
+      home: from("homeOutline", "@iconify-icons/material-symbols/home-outline"),
+      about: from(
+        "infoOutline",
+        "@iconify-icons/material-symbols/info-outline",
+      ),
+    },
+    showcase: {
+      ...from(
+        "favoriteOutline",
+        "@iconify-icons/material-symbols/favorite-outline",
+      ),
+      label: "Material Symbols",
+    },
+  },
+  fontawesome: {
+    title: "Font Awesome",
+    packages: {
+      "@iconify-icons/fa7-solid": "^2.0.0",
+      "@iconify-icons/fa7-regular": "^2.0.0",
+      "@iconify-icons/fa7-brands": "^2.0.0",
+    },
+    nav: {
+      home: from("house", "@iconify-icons/fa7-solid/house"),
+      about: from("circleInfo", "@iconify-icons/fa7-solid/circle-info"),
+    },
+    showcase: {
+      ...from("fontAwesome", "@iconify-icons/fa7-brands/font-awesome"),
+      label: "Font Awesome",
+    },
+  },
+  lucide: {
+    title: "Lucide",
+    packages: { "@iconify-icons/lucide": "^2.0.22" },
+    nav: {
+      home: from("house", "@iconify-icons/lucide/house"),
+      about: from("info", "@iconify-icons/lucide/info"),
+    },
+    showcase: {
+      ...from("sparkles", "@iconify-icons/lucide/sparkles"),
+      label: "Lucide",
+    },
+  },
+}
+
+// The languages offered for the example app, with its few texts in each.
+export const LANGUAGES = {
+  en: language("English", {
+    nav: { home: "Home", about: "About" },
+    language: "Language",
+    home: { title: "Welcome", hint: "Click a greeting to shout it." },
+    about: { title: "About", body: "A page of its own, at its own address." },
+    message: { hello: "Hello {{who}}" },
+  }),
+  it: language("Italiano", {
+    nav: { home: "Home", about: "Info" },
+    language: "Lingua",
+    home: { title: "Benvenuto", hint: "Clicca un saluto per urlarlo." },
+    about: { title: "Info", body: "Una pagina tutta sua, al suo indirizzo." },
+    message: { hello: "Ciao {{who}}" },
+  }),
+  fr: language("Français", {
+    nav: { home: "Accueil", about: "À propos" },
+    language: "Langue",
+    home: { title: "Bienvenue", hint: "Cliquez sur un salut pour le crier." },
+    about: {
+      title: "À propos",
+      body: "Une page à part entière, à sa propre adresse.",
+    },
+    message: { hello: "Bonjour {{who}}" },
+  }),
+  de: language("Deutsch", {
+    nav: { home: "Start", about: "Über" },
+    language: "Sprache",
+    home: {
+      title: "Willkommen",
+      hint: "Klicke auf einen Gruß, um ihn zu rufen.",
+    },
+    about: { title: "Über", body: "Eine eigene Seite unter eigener Adresse." },
+    message: { hello: "Hallo {{who}}" },
+  }),
+  es: language("Español", {
+    nav: { home: "Inicio", about: "Acerca de" },
+    language: "Idioma",
+    home: { title: "Bienvenido", hint: "Haz clic en un saludo para gritarlo." },
+    about: {
+      title: "Acerca de",
+      body: "Una página propia, en su propia dirección.",
+    },
+    message: { hello: "Hola {{who}}" },
+  }),
+  pt: language("Português", {
+    nav: { home: "Início", about: "Sobre" },
+    language: "Idioma",
+    home: { title: "Bem-vindo", hint: "Clique numa saudação para gritá-la." },
+    about: {
+      title: "Sobre",
+      body: "Uma página própria, no seu próprio endereço.",
+    },
+    message: { hello: "Olá {{who}}" },
+  }),
+  ja: language("日本語", {
+    nav: { home: "ホーム", about: "概要" },
+    language: "言語",
+    home: {
+      title: "ようこそ",
+      hint: "あいさつをクリックすると大きくなります。",
+    },
+    about: { title: "概要", body: "専用のアドレスを持つ独立したページです。" },
+    message: { hello: "こんにちは、{{who}}" },
+  }),
+  ar: language("العربية", {
+    nav: { home: "الرئيسية", about: "حول" },
+    language: "اللغة",
+    home: { title: "مرحبًا", hint: "انقر على تحية لتكبيرها." },
+    about: { title: "حول", body: "صفحة مستقلة بعنوانها الخاص." },
+    message: { hello: "مرحبًا {{who}}" },
+  }),
+}
+
+function from(name, source) {
+  return { name, from: source }
+}
+
+function language(title, texts) {
+  return { title, texts }
+}

package/bin/lib/file.js

@@ -0,0 +1,88 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import {
+  AFTER_FIRST_CHARACTER_INDEX,
+  FIRST_CHARACTER_INDEX,
+  FIRST_ITEM_INDEX,
+} from "./constants.js"
+
+export function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.name === "gitignore") {
+      fs.copyFileSync(srcPath, path.join(dest, ".gitignore"))
+      continue
+    }
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      fs.copyFileSync(srcPath, destPath)
+    }
+  }
+}
+
+export function findMainPath(targetDir) {
+  const candidates = [
+    path.join(targetDir, "src/main.ts"),
+    path.join(targetDir, "src/main.js"),
+  ]
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null
+}
+
+export function findViteConfigPath(targetDir) {
+  const candidates = [
+    path.join(targetDir, "vite.config.ts"),
+    path.join(targetDir, "vite.config.js"),
+  ]
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null
+}
+
+export function injectAfterImport(source, importSource, newImport) {
+  const importLinePattern = new RegExp(
+    `^([ \\t]*import .+ from "${escapeRegExp(importSource)}"\\r?\\n)`,
+    "m",
+  )
+
+  if (!importLinePattern.test(source)) {
+    return `${newImport}${EOL}${source}`
+  }
+
+  return source.replace(
+    importLinePattern,
+    (match) => `${match}${newImport}${EOL}`,
+  )
+}
+
+export function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+export function toJavaIdentifier(value) {
+  const identifier = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .split(" ")
+    .filter(Boolean)
+    .map((part, index) =>
+      index === FIRST_ITEM_INDEX
+        ? part
+        : part.charAt(FIRST_CHARACTER_INDEX).toUpperCase() +
+          part.slice(AFTER_FIRST_CHARACTER_INDEX),
+    )
+    .join("")
+    .replace(/^[^a-z]+/, "")
+
+  return identifier || "app"
+}

package/bin/lib/imports.js

@@ -0,0 +1,64 @@
+// Import statements in the order eslint-plugin-simple-import-sort gives them,
+// so a generated project passes `eslint` as it is: side-effect imports first,
+// in the order given, then packages, then relative modules, a blank line
+// between groups.
+
+const collator = new Intl.Collator("en", { sensitivity: "base", numeric: true })
+
+/**
+ * @param {string[]} lines - One import statement each.
+ * @returns {string}
+ */
+export function importBlock(lines) {
+  const sideEffects = []
+  const packages = []
+  const relative = []
+
+  for (const line of lines) {
+    const source = sourceOf(line)
+    if (!line.includes(" from ")) sideEffects.push(line)
+    else if (source.startsWith(".")) relative.push(line)
+    else packages.push(line)
+  }
+
+  return [sideEffects, sortImports(packages), sortImports(relative)]
+    .filter((group) => group.length)
+    .map((group) => group.join("\n"))
+    .join("\n\n")
+}
+
+function sortImports(lines) {
+  return lines
+    .map((line) => ({ line, source: sourceOf(line) }))
+    .sort(
+      (a, b) =>
+        compare(normalize(a.source), normalize(b.source)) ||
+        compare(a.source, b.source) ||
+        // Type imports before regular ones from the same module.
+        Number(b.line.startsWith("import type")) -
+          Number(a.line.startsWith("import type")),
+    )
+    .map(({ line }) => line)
+}
+
+// The plugin's own normalization: by directory level, `.` and `/` before any
+// other punctuation.
+function normalize(source) {
+  return source
+    .replace(/^[./]*\.$/, "$&/")
+    .replace(/^[./]*\/$/, "$&,")
+    .replace(
+      /[./_-]/g,
+      (char) => ({ ".": "_", "/": "-", _: ".", "-": "/" })[char],
+    )
+}
+
+function compare(a, b) {
+  return collator.compare(a, b) || Number(a > b) - Number(a < b)
+}
+
+// The module an import statement imports from.
+function sourceOf(line) {
+  const [, source] = line.match(/"([^"]+)"/)
+  return source
+}

package/bin/lib/mobile.js

@@ -0,0 +1,140 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import { CAPACITOR_VERSION, TYPESCRIPT_VERSION } from "./constants.js"
+import { toJavaIdentifier } from "./file.js"
+
+export function addMobileSupport(targetDir, pkg, projectName) {
+  pkg.dependencies ??= {}
+  pkg.devDependencies ??= {}
+  pkg.scripts ??= {}
+
+  pkg.dependencies["@capacitor/core"] = CAPACITOR_VERSION
+  pkg.devDependencies["@capacitor/android"] = CAPACITOR_VERSION
+  pkg.devDependencies["@capacitor/cli"] = CAPACITOR_VERSION
+  pkg.devDependencies["@capacitor/ios"] = CAPACITOR_VERSION
+  // For capacitor.config.ts. A TypeScript template already has its own, which
+  // its code is written against.
+  pkg.devDependencies["typescript"] ??= TYPESCRIPT_VERSION
+
+  pkg.scripts.cap = "cap"
+  pkg.scripts["mobile:init:ios"] = "cap add ios"
+  pkg.scripts["mobile:init:android"] = "cap add android"
+  pkg.scripts["mobile:sync"] = "pnpm build && cap sync"
+  pkg.scripts["mobile:ios"] = "pnpm build && cap run ios"
+  pkg.scripts["mobile:android"] = "pnpm build && cap run android"
+
+  fs.writeFileSync(
+    path.join(targetDir, "capacitor.config.ts"),
+    createCapacitorConfigSource(projectName),
+  )
+  includeInNodeProject(targetDir, "capacitor.config.ts")
+
+  appendMobileSetupToReadme(targetDir)
+}
+
+// A TypeScript template type-checks and lints its config files through
+// tsconfig.node.json, so a new one has to be listed there. Edited as text, so
+// the `include` line keeps the one-line layout Prettier gives it.
+function includeInNodeProject(targetDir, file) {
+  const tsconfigPath = path.join(targetDir, "tsconfig.node.json")
+  if (!fs.existsSync(tsconfigPath)) return
+
+  const tsconfig = fs.readFileSync(tsconfigPath, "utf-8")
+  if (tsconfig.includes(`"${file}"`)) return
+  fs.writeFileSync(
+    tsconfigPath,
+    tsconfig.replace(/("include": \[[^\]]*)\]/, `$1, "${file}"]`),
+  )
+}
+
+export function appendMobileSetupToReadme(targetDir) {
+  const readmePath = path.join(targetDir, "README.md")
+  if (!fs.existsSync(readmePath)) {
+    return
+  }
+
+  const readme = fs.readFileSync(readmePath, "utf-8")
+  if (readme.includes("## Mobile Setup")) {
+    return
+  }
+
+  const mobileReadme = `
+## Mobile Setup
+
+This project includes Capacitor for Android and iOS support.
+
+Please note that mobile development depends on external platform tooling that is not installed or managed by the CLI. If the app does not just work after scaffolding, it is usually because one or more native prerequisites are missing on the machine.
+
+### Android
+
+Before you run the native apps, make sure you have:
+
+- Android Studio installed with the Android SDK: https://developer.android.com/studio
+- A Java Development Kit compatible with Capacitor. Capacitor is currently known to work reliably with JDK 21, so prefer JDK 21 over newer versions if you run into Java compatibility errors.
+- The SDK path available via ANDROID_HOME (for example, on macOS this is often $HOME/Library/Android/sdk)
+
+On macOS, the following shell variables are commonly needed:
+
+\`\`\`bash
+export JAVA_HOME="/path/to/jdk-21"
+export ANDROID_HOME="$HOME/Library/Android/sdk"
+export PATH="$ANDROID_HOME/platform-tools:$PATH"
+\`\`\`
+
+### iOS
+
+For iOS you also need the Apple toolchain and device setup on a Mac:
+
+- Xcode from the App Store
+- iOS development tools and simulator components (this can be very large, often multiple GB)
+- A valid Apple Developer team / signing identity in Xcode
+- Device trust setup for your iPhone in Settings > General > VPN & Device Management
+
+The most common first-time setup commands are:
+
+\`\`\`bash
+sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+\`\`\`
+
+If you are using a physical device, you may also need to approve the developer certificate on the device and ensure the app is signed with a valid team.
+
+### Official resources
+
+- Android: https://capacitorjs.com/docs/android
+- iOS: https://capacitorjs.com/docs/ios
+- Android Studio: https://developer.android.com/studio
+- Xcode: https://developer.apple.com/xcode/
+
+Then sync and open the native project:
+
+\`\`\`bash
+pnpm mobile:sync
+pnpm mobile:android
+# or
+pnpm mobile:ios
+\`\`\`
+`
+
+  fs.writeFileSync(
+    readmePath,
+    `${readme.trimEnd()}${EOL}${EOL}${mobileReadme.trim()}${EOL}`,
+  )
+}
+
+export function createCapacitorConfigSource(projectName) {
+  const appId = `com.inglorious.${toJavaIdentifier(projectName)}`
+
+  return `import type { CapacitorConfig } from "@capacitor/cli"
+
+const config: CapacitorConfig = {
+  appId: "${appId}",
+  appName: "${projectName}",
+  webDir: "dist",
+}
+
+export default config
+`
+}

package/bin/lib/pwa.js

@@ -0,0 +1,168 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import {
+  VITE_PLUGIN_PWA_VERSION,
+  VITE_PWA_ASSETS_GENERATOR_VERSION,
+  WORKBOX_WINDOW_VERSION,
+} from "./constants.js"
+import { findMainPath, findViteConfigPath, injectAfterImport } from "./file.js"
+
+export function addPwaSupport(targetDir, pkg, projectName) {
+  pkg.devDependencies ??= {}
+  pkg.devDependencies["vite-plugin-pwa"] = VITE_PLUGIN_PWA_VERSION
+  pkg.devDependencies["@vite-pwa/assets-generator"] =
+    VITE_PWA_ASSETS_GENERATOR_VERSION
+  pkg.devDependencies["workbox-window"] = WORKBOX_WINDOW_VERSION
+
+  const publicDir = path.join(targetDir, "public")
+  fs.mkdirSync(publicDir, { recursive: true })
+
+  injectPwaPluginConfig(targetDir, projectName)
+  writePwaRegistration(targetDir)
+  injectServiceWorkerRegistration(targetDir)
+}
+
+export function injectServiceWorkerRegistration(targetDir) {
+  const mainPath = findMainPath(targetDir)
+
+  if (!mainPath) {
+    return
+  }
+
+  let main = fs.readFileSync(mainPath, "utf-8")
+
+  if (!main.includes("./pwa")) {
+    main = injectSideEffectImport(main, `import "./pwa"`)
+  }
+
+  fs.writeFileSync(mainPath, main)
+}
+
+export function injectPwaPluginConfig(targetDir, projectName) {
+  const viteConfigPath = findViteConfigPath(targetDir)
+
+  if (!viteConfigPath) {
+    return
+  }
+
+  let viteConfig = fs.readFileSync(viteConfigPath, "utf-8")
+
+  if (!viteConfig.includes("vite-plugin-pwa")) {
+    // Right after the image optimizer, where the imports' alphabetical order
+    // puts it.
+    viteConfig = injectAfterImport(
+      viteConfig,
+      viteConfig.includes("vite-plugin-image-optimizer")
+        ? "vite-plugin-image-optimizer"
+        : "vite",
+      `import { VitePWA } from "vite-plugin-pwa"`,
+    )
+  }
+
+  if (!viteConfig.includes("VitePWA(")) {
+    // One plugin per line, as Prettier prints a list this long.
+    viteConfig = viteConfig.replace(
+      /plugins: \[(.*)\],/,
+      (_, plugins) =>
+        `plugins: [${EOL}${[
+          createVitePwaConfig(projectName),
+          ...splitPlugins(plugins),
+        ]
+          .map((plugin) => `    ${plugin},`)
+          .join(EOL)}${EOL}  ],`,
+    )
+  }
+
+  fs.writeFileSync(viteConfigPath, viteConfig)
+}
+
+export function writePwaRegistration(targetDir) {
+  const mainPath = findMainPath(targetDir)
+
+  if (!mainPath) {
+    return
+  }
+
+  const extension = path.extname(mainPath)
+  const pwaPath = path.join(targetDir, `src/pwa${extension}`)
+
+  fs.writeFileSync(pwaPath, createPwaRegistrationSource(extension))
+}
+
+export function createPwaRegistrationSource(extension) {
+  if (extension === ".ts") {
+    return `/// <reference types="vite-plugin-pwa/client" />
+import { isNative } from "@inglorious/web/mobile"
+import { registerSW } from "virtual:pwa-register"
+
+if (!isNative()) {
+  registerSW()
+}
+`
+  }
+
+  return `import { isNative } from "@inglorious/web/mobile"
+import { registerSW } from "virtual:pwa-register"
+
+if (!isNative()) {
+  registerSW()
+}
+`
+}
+
+export function createVitePwaConfig(projectName) {
+  return `VitePWA({
+      injectRegister: false,
+      registerType: "autoUpdate",
+      pwaAssets: {
+        image: "public/logo.png",
+        preset: "minimal-2023",
+      },
+      manifest: {
+        name: "${projectName}",
+        short_name: "${projectName}",
+        description: "An Inglorious Web app.",
+        theme_color: "#ffffff",
+        background_color: "#ffffff",
+        display: "standalone",
+        start_url: "/",
+      },
+    })`
+}
+
+// The plugins of a one-line `plugins: [a(), b({ c: 1 })]`, split at the
+// top-level commas.
+function splitPlugins(source) {
+  const plugins = []
+  let depth = 0
+  let current = ""
+  for (const char of source) {
+    if ("([{".includes(char)) depth++
+    if (")]}".includes(char)) depth--
+    if (char === "," && !depth) {
+      plugins.push(current.trim())
+      current = ""
+    } else {
+      current += char
+    }
+  }
+  if (current.trim()) plugins.push(current.trim())
+  return plugins
+}
+
+// A side-effect import goes with the others at the top, in the order they
+// come, as eslint-plugin-simple-import-sort keeps them.
+function injectSideEffectImport(source, newImport) {
+  const lastSideEffect = source
+    .split(EOL)
+    .findLast((line) => /^import ["']/.test(line))
+  if (lastSideEffect) {
+    return source.replace(
+      `${lastSideEffect}${EOL}`,
+      `${lastSideEffect}${EOL}${newImport}${EOL}`,
+    )
+  }
+  return `${newImport}${EOL}${EOL}${source}`
+}