@inglorious/create-app 1.1.1 → 1.2.0

package/README.md

@@ -23,17 +23,25 @@ pnpm create @inglorious/app
 
 The CLI will guide you through the setup process, asking for a project name and which template you'd like to use.
 
-For JavaScript and TypeScript Vite app templates, the CLI can also add optional app targets:
+For the JavaScript and TypeScript Vite templates, the CLI then asks about the app's features:
+
+| Question                  | Flag                                                 | Adds                                                                                                  |
+| ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Use Inglorious UI?        | `--ui` / `--no-ui`                                   | `@inglorious/ui`, its base styles and an app bar                                                      |
+| Which theme?              | `--theme=inglorious\|material\|bootstrap`            | The theme's stylesheet and class                                                                      |
+| Is it a mobile app?       | `--mobile` / `--no-mobile`                           | Capacitor for Android and iOS; with Inglorious UI, a bottom tab bar and safe-area spacing             |
+| Add routing?              | `--routing` / `--no-routing`                         | The Router, a home and an about page, and navigation between them                                     |
+| Animate page transitions? | `--transitions` / `--no-transitions`                 | View transitions between pages (with routing and Inglorious UI)                                       |
+| Which icon packs?         | `--icons=material,fontawesome,lucide` / `--no-icons` | Iconify icon sets, drawn by Inglorious UI's `Icon` (with Inglorious UI)                               |
+| Translate the app?        | `--i18n` / `--no-i18n`, `--languages=en,it`          | `@inglorious/i18n`, a catalogue per language and a language picker; the first language is the default |
+| Enable PWA support?       | `--pwa` / `--no-pwa`                                 | `vite-plugin-pwa`, a manifest, icons and service worker registration                                  |
+
+The app is generated in the syntax you chose: lit-html, JSX or Vue. Every question answered by a flag is skipped:
 
 ```bash
-npm create @inglorious/app@latest -- --pwa
-npm create @inglorious/app@latest -- --mobile
-npm create @inglorious/app@latest -- --pwa --mobile
+npm create @inglorious/app@latest -- --ui --theme=material --routing --transitions --icons=material --languages=en,it --mobile
 ```
 
-- `--pwa` adds a web app manifest, service worker, and browser-only service worker registration.
-- `--mobile` adds Capacitor dependencies, config, and mobile scripts for iOS and Android.
-
 ## Templates
 
 The following templates are available to get you started:
@@ -61,10 +69,19 @@ pnpm install
 pnpm dev
 ```
 
-When mobile support is enabled, build and sync native projects with:
+When mobile support is enabled, initialize the native platforms once, then build and sync them with:
 
 ```bash
+# Run one or both commands once, depending on the platforms you need
+pnpm mobile:init:android
+pnpm mobile:init:ios
+
 pnpm mobile:sync
+
+# Build and open the native app
+pnpm mobile:android
+# or
+pnpm mobile:ios
 ```
 
 For Android and iOS builds, install Android Studio with the Android SDK and a Java runtime compatible with Capacitor. Capacitor currently works reliably with JDK 21, so prefer JDK 21 over newer Java versions if you hit Java compatibility issues. Set `JAVA_HOME` to your JDK 21 install and `ANDROID_HOME` to your Android SDK path before running the native app. See the official Capacitor setup guides for platform-specific instructions:

package/bin/index.js

@@ -8,15 +8,18 @@ import path from "path"
 import prompts from "prompts"
 import { fileURLToPath } from "url"
 
-const INDENTATION = 2
-const CAPACITOR_VERSION = "^8.5.0"
-const AFTER_FIRST_CHARACTER_INDEX = 1
-const EMPTY_LENGTH = 0
-const FIRST_CHARACTER_INDEX = 0
-const FIRST_ITEM_INDEX = 0
-const NPM_VIEW_TIMEOUT_MS = 10_000
-const USER_ARG_START_INDEX = 2
-const VITE_APP_TEMPLATES = new Set(["js", "ts"])
+import { addAppFeatures } from "./lib/app.js"
+import { parseCliOptions } from "./lib/cli.js"
+import {
+  INDENTATION,
+  NPM_VIEW_TIMEOUT_MS,
+  USER_ARG_START_INDEX,
+  VITE_APP_TEMPLATES,
+} from "./lib/constants.js"
+import { copyDir } from "./lib/file.js"
+import { addMobileSupport } from "./lib/mobile.js"
+import { addPwaSupport } from "./lib/pwa.js"
+import { askAppFeatures } from "./lib/questions.js"
 
 async function main() {
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -80,10 +83,7 @@ async function main() {
   }
 
   let renderer = "lit-html"
-  let pwa = cliOptions.pwa === true
-  let mobile = cliOptions.mobile === true
 
-  // Ask about renderer for non-minimal templates
   if (baseTemplate !== "minimal") {
     const { selectedRenderer } = await prompts(
       {
@@ -119,46 +119,26 @@ async function main() {
     renderer = selectedRenderer
   }
 
-  const supportsAppFeatures = VITE_APP_TEMPLATES.has(baseTemplate)
-
-  if (supportsAppFeatures) {
-    const featureQuestions = []
-
-    if (cliOptions.pwa === null) {
-      featureQuestions.push({
-        type: "confirm",
-        name: "pwa",
-        message: "Enable PWA support?",
-        initial: false,
-      })
-    }
-
-    if (cliOptions.mobile === null) {
-      featureQuestions.push({
-        type: "confirm",
-        name: "mobile",
-        message: "Add hybrid mobile support with Capacitor?",
-        initial: false,
-      })
-    }
-
-    if (featureQuestions.length > EMPTY_LENGTH) {
-      const answers = await prompts(featureQuestions, { onCancel })
+  let features = {
+    ui: false,
+    routing: false,
+    icons: [],
+    languages: [],
+    mobile: false,
+    pwa: false,
+  }
 
-      if (canceled) {
-        console.log("Operation canceled.")
-        return
-      }
+  if (VITE_APP_TEMPLATES.has(baseTemplate)) {
+    features = await askAppFeatures(cliOptions)
 
-      pwa = cliOptions.pwa === true ? true : answers.pwa === true
-      mobile = cliOptions.mobile === true ? true : answers.mobile === true
+    if (!features) {
+      console.log("Operation canceled.")
+      return
     }
-  } else if (pwa || mobile) {
+  } else if (cliOptions.pwa || cliOptions.mobile) {
     console.warn(
       "PWA and mobile options are only available for JavaScript and TypeScript Vite app templates.",
     )
-    pwa = false
-    mobile = false
   }
 
   const spinner = ora(`Creating project "${projectName}"...`).start()
@@ -166,18 +146,14 @@ async function main() {
   try {
     const targetDir = path.join(process.cwd(), projectName)
 
-    // Determine the actual template directory based on base template and renderer
     let templateName = baseTemplate
     if (baseTemplate !== "minimal" && renderer !== "lit-html") {
       templateName = `${baseTemplate}-${renderer}`
     }
 
     const templateDir = path.join(templatesRoot, templateName)
-
-    // Create project directory and copy template files
     copyDir(templateDir, targetDir)
 
-    // Update README.md with project name
     const readmePath = path.join(targetDir, "README.md")
     if (fs.existsSync(readmePath)) {
       let readme = fs.readFileSync(readmePath, "utf-8")
@@ -190,372 +166,74 @@ async function main() {
       console.log(`\nNext steps:`)
       console.log(`  cd ${projectName}`)
       console.log(`  Open index.html in your browser`)
-    } else {
-      // Update package.json with project name
-      const pkgPath = path.join(targetDir, "package.json")
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
-      pkg.name = projectName
+      return
+    }
 
-      if (pwa) {
-        spinner.text = "Adding PWA support..."
-        addPwaSupport(targetDir, projectName)
-      }
+    const pkgPath = path.join(targetDir, "package.json")
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
+    pkg.name = projectName
+
+    const hasAppFeatures =
+      features.ui ||
+      features.routing ||
+      Boolean(features.icons.length) ||
+      Boolean(features.languages.length)
+
+    if (hasAppFeatures) {
+      spinner.text = "Adding app features..."
+      addAppFeatures(targetDir, pkg, {
+        ...features,
+        projectName,
+        isTypeScript: baseTemplate === "ts",
+        renderer,
+      })
+    }
 
-      if (mobile) {
-        spinner.text = "Adding Capacitor support..."
-        addMobileSupport(targetDir, pkg, projectName, templateName)
-      }
+    if (features.pwa) {
+      spinner.text = "Adding PWA support..."
+      addPwaSupport(targetDir, pkg, projectName)
+    }
+
+    if (features.mobile) {
+      spinner.text = "Adding Capacitor support..."
+      addMobileSupport(targetDir, pkg, projectName)
+    }
 
-      for (const depType of ["dependencies", "devDependencies"]) {
-        if (pkg[depType]) {
-          for (const [name, version] of Object.entries(pkg[depType])) {
-            if (version.startsWith("workspace:")) {
-              spinner.text = `Fetching latest version of ${name}...`
-              pkg[depType][name] = getLatestVersion(name)
-            }
+    for (const depType of ["dependencies", "devDependencies"]) {
+      if (pkg[depType]) {
+        for (const [name, version] of Object.entries(pkg[depType])) {
+          if (version.startsWith("workspace:")) {
+            spinner.text = `Fetching latest version of ${name}...`
+            pkg[depType][name] = getLatestVersion(name)
           }
         }
       }
+    }
 
-      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, INDENTATION) + EOL)
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, INDENTATION) + EOL)
 
-      spinner.succeed(`Created ${projectName} at ${targetDir}`)
-      console.log(`\nNext steps:`)
-      console.log(`  cd ${projectName}`)
-      console.log(`  pnpm install`)
-      console.log(`  pnpm dev`)
-    }
+    spinner.succeed(`Created ${projectName} at ${targetDir}`)
+    console.log(`\nNext steps:`)
+    console.log(`  cd ${projectName}`)
+    console.log(`  pnpm install`)
+    console.log(`  pnpm dev`)
   } catch (error) {
     spinner.fail("Operation failed.")
     console.error(error)
   }
-
-  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)
-
-      // Rename gitignore to .gitignore
-      if (entry.name === "gitignore") {
-        fs.copyFileSync(srcPath, path.join(dest, ".gitignore"))
-        continue
-      }
-
-      if (entry.isDirectory()) {
-        copyDir(srcPath, destPath)
-      } else {
-        fs.copyFileSync(srcPath, destPath)
-      }
-    }
-  }
-
-  function getLatestVersion(packageName) {
-    try {
-      const version = execSync(`npm view ${packageName} version`, {
-        encoding: "utf-8",
-        stdio: "pipe", // Prevent npm view output from cluttering the console
-        timeout: NPM_VIEW_TIMEOUT_MS,
-      }).trim()
-      return `^${version}`
-    } catch {
-      return "latest" // fallback
-    }
-  }
-}
-
-function parseCliOptions(args) {
-  return {
-    mobile: readBooleanFlag(args, "mobile"),
-    pwa: readBooleanFlag(args, "pwa"),
-  }
-}
-
-function readBooleanFlag(args, name) {
-  if (args.includes(`--${name}`)) {
-    return true
-  }
-
-  if (args.includes(`--no-${name}`)) {
-    return false
-  }
-
-  return null
-}
-
-function addPwaSupport(targetDir, projectName) {
-  const publicDir = path.join(targetDir, "public")
-  fs.mkdirSync(publicDir, { recursive: true })
-  fs.writeFileSync(path.join(publicDir, "sw.js"), createServiceWorkerSource())
-  fs.writeFileSync(
-    path.join(publicDir, "manifest.webmanifest"),
-    JSON.stringify(createWebManifest(projectName), null, INDENTATION) + EOL,
-  )
-
-  injectPwaHeadTags(path.join(targetDir, "index.html"))
-  injectServiceWorkerRegistration(targetDir)
-}
-
-function addMobileSupport(targetDir, pkg, projectName, templateName) {
-  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
-
-  pkg.scripts.cap = "cap"
-  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"
-
-  const extension = templateName.startsWith("ts") ? "ts" : "js"
-  fs.writeFileSync(
-    path.join(targetDir, `capacitor.config.ts`), // HACK: apparently only ts config works!
-    createCapacitorConfigSource(projectName, extension),
-  )
-
-  appendMobileSetupToReadme(targetDir)
-}
-
-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}`,
-  )
-}
-
-function createServiceWorkerSource() {
-  return `const CACHE_NAME = "inglorious-app-v1"
-const APP_SHELL = ["/", "/index.html", "/logo.png", "/style.css"]
-
-self.addEventListener("install", (event) => {
-  event.waitUntil(
-    caches.open(CACHE_NAME).then((cache) => cache.addAll(APP_SHELL)),
-  )
-  self.skipWaiting()
-})
-
-self.addEventListener("activate", (event) => {
-  event.waitUntil(
-    caches
-      .keys()
-      .then((keys) =>
-        Promise.all(keys.map((key) => key === CACHE_NAME ? null : caches.delete(key))),
-      ),
-  )
-  self.clients.claim()
-})
-
-self.addEventListener("fetch", (event) => {
-  if (event.request.method !== "GET") {
-    return
-  }
-
-  event.respondWith(
-    caches.match(event.request).then((cachedResponse) => {
-      if (cachedResponse) {
-        return cachedResponse
-      }
-
-      return fetch(event.request).catch(() => {
-        if (event.request.mode === "navigate") {
-          return caches.match("/index.html")
-        }
-
-        throw new Error("Network request failed")
-      })
-    }),
-  )
-})
-`
 }
 
-function createWebManifest(projectName) {
-  return {
-    name: projectName,
-    short_name: projectName,
-    description: "An Inglorious Web app.",
-    start_url: "/",
-    display: "standalone",
-    background_color: "#ffffff",
-    theme_color: "#111827",
-    icons: [
-      {
-        src: "/logo.png",
-        sizes: "192x192",
-        type: "image/png",
-      },
-      {
-        src: "/logo.png",
-        sizes: "512x512",
-        type: "image/png",
-      },
-    ],
-  }
-}
-
-function injectPwaHeadTags(indexPath) {
-  let index = fs.readFileSync(indexPath, "utf-8")
-
-  if (!index.includes('rel="manifest"')) {
-    index = index.replace(
-      /^([ \t]*<link rel="icon"[^>]*>\r?\n)/m,
-      `$1    <link rel="manifest" href="/manifest.webmanifest" />${EOL}`,
-    )
-  }
-
-  if (!index.includes('name="theme-color"')) {
-    index = index.replace(
-      /^([ \t]*<meta name="viewport"[^>]*>\r?\n)/m,
-      `$1    <meta name="theme-color" content="#111827" />${EOL}`,
-    )
-  }
-
-  fs.writeFileSync(indexPath, index)
-}
-
-function injectServiceWorkerRegistration(targetDir) {
-  const mainPath = findMainPath(targetDir)
-
-  if (!mainPath) {
-    return
-  }
-
-  let main = fs.readFileSync(mainPath, "utf-8")
-
-  if (!main.includes("@inglorious/web/mobile")) {
-    main = main.replace(
-      /^([ \t]*import \{ mount \} from "@inglorious\/web"\r?\n)/m,
-      (match) =>
-        `${match}import { isNative } from "@inglorious/web/mobile"${EOL}`,
-    )
-  }
-
-  if (!main.includes('navigator.serviceWorker.register("/sw.js")')) {
-    main = `${main.trimEnd()}${EOL}${EOL}if (!isNative() && "serviceWorker" in navigator) {
-  navigator.serviceWorker.register("/sw.js")
-}${EOL}`
+function getLatestVersion(packageName) {
+  try {
+    const version = execSync(`npm view ${packageName} version`, {
+      encoding: "utf-8",
+      stdio: "pipe",
+      timeout: NPM_VIEW_TIMEOUT_MS,
+    }).trim()
+    return `^${version}`
+  } catch {
+    return "latest"
   }
-
-  fs.writeFileSync(mainPath, main)
-}
-
-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
-}
-
-function createCapacitorConfigSource(projectName /* , extension */) {
-  const appId = `com.inglorious.${toJavaIdentifier(projectName)}`
-
-  //if (extension === "ts") { // HACK: apparently only ts config files work!
-  return `import type { CapacitorConfig } from "@capacitor/cli"
-
-const config: CapacitorConfig = {
-  appId: "${appId}",
-  appName: "${projectName}",
-  webDir: "dist",
-}
-
-export default config
-`
-}
-
-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"
 }
 
 main().catch((e) => {