@inglorious/capacitor 0.3.0 → 0.4.0

package/README.md

@@ -5,6 +5,7 @@
 Native project setup for [Capacitor](https://capacitorjs.com) apps, written once in `package.json` instead of clicked through Xcode and Android Studio. `@inglorious/create-app --mobile` sets it up for you.
 
 - `inglorious-capacitor configure` writes the app's native settings into `android/` and `ios/` after every `cap sync`: App Links and Universal Links, the signing team, push, Analytics off until consent and without the advertising ID, permissions and Info.plist entries, and the Firebase files.
+- `inglorious-capacitor dev <ios|android>` runs the app on a device or emulator with live reload from the Vite dev server.
 - `inglorious-capacitor assets` makes every icon and splash screen, light and dark, from one logo.
 - `inglorious-capacitor listing-assets` captures store screenshots of the running app in every size and language, and makes the promotional images (Google Play's feature graphic, a header and a search results card) and Google Play's 512px icon.
 
@@ -22,6 +23,8 @@ Run `configure` as Capacitor's `sync` hook, so `cap add` and `cap sync` both app
     "capacitor:sync:after": "inglorious-capacitor configure",
     "mobile:init:ios": "cap add ios && inglorious-capacitor assets --ios",
     "mobile:init:android": "cap add android && inglorious-capacitor assets --android",
+    "mobile:dev:ios": "inglorious-capacitor dev ios",
+    "mobile:dev:android": "inglorious-capacitor dev android",
     "mobile:assets": "inglorious-capacitor assets",
     "mobile:listing-assets": "inglorious-capacitor listing-assets"
   }
@@ -105,6 +108,10 @@ It runs for the platform Capacitor is syncing, and changes nothing when the sett
 
 It centres the logo (`public/logo.svg` or `public/logo.png` by default) on `background` for the icons and the splash screen, and on `backgroundDark` for the dark splash screen, then hands the result to [`@capacitor/assets`](https://github.com/ionic-team/capacitor-assets) for every size and density. `iconScale` and `splashScale` are the logo's width as a share of the icon and of the splash screen. Pass `--ios` or `--android` for one platform.
 
+## Live reload on a device
+
+`inglorious-capacitor dev ios` (or `android`) starts Vite on the local network (`vite --host`) and runs `cap run ios --live-reload`, which points the installed app at it: every saved file reloads on the phone. The phone must be on the same network as the computer. It builds the web app first if `webDir` has none, since `cap run` syncs it. Further options go to `cap run`, such as `--target <id>`; `--port=<port>` changes Vite's port (5173 by default). Ctrl+C stops both, and Capacitor puts the native config back.
+
 ## Store listing images
 
 `listing-assets` opens the running app in your installed Chrome (through `playwright-core`, so no browser download) and captures the screens listed in `listing.config.js`, once per device and language:

package/bin/inglorious-capacitor.js

@@ -5,6 +5,9 @@ const USAGE = `Usage: inglorious-capacitor <command>
 
   configure            Apply the "native" settings in package.json to the
                        native projects (runs after every cap sync)
+  dev <ios|android> [--port=5173] [cap run options]
+                       Run the app on a device or emulator with live reload
+                       from the Vite dev server
   assets [--ios] [--android]
                        Make the app icons and splash screens from the logo
   listing-assets       Capture store screenshots of the running app, and make
@@ -21,6 +24,15 @@ try {
     const { configure } = await import("../src/configure/index.js")
     const platforms = await configure()
     if (platforms.length) console.log(`Configured ${platforms.join(" and ")}`)
+  } else if (command === "dev") {
+    const { dev } = await import("../src/dev/index.js")
+    const [platform, ...rest] = flags
+    const portFlag = rest.find((flag) => flag.startsWith("--port="))
+    process.exitCode = await dev({
+      platform,
+      port: portFlag ? Number(portFlag.slice("--port=".length)) : undefined,
+      args: rest.filter((flag) => flag !== portFlag),
+    })
   } else if (command === "assets") {
     const { assets } = await import("../src/assets/index.js")
     await assets({ platforms: flags.map((flag) => flag.replace(/^--/, "")) })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/capacitor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Configures Capacitor's native projects from package.json, makes their icons and splash screens from one logo, and the screenshots and graphics the stores ask for.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/config.js

@@ -41,6 +41,7 @@ export async function readSettings(root, env = process.env) {
     root,
     appId: capacitor.appId,
     appName: capacitor.appName,
+    webDir: capacitor.webDir ?? "www",
     appLinks: native.appLinks?.domain
       ? normalizeAppLinks(native.appLinks)
       : null,

package/src/dev/dev.test.js

@@ -0,0 +1,103 @@
+import { EventEmitter } from "node:events"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { dev } from "./index.js"
+
+const CAPACITOR_CONFIG = {
+  appId: "com.example.app",
+  appName: "Example",
+  webDir: "dist",
+}
+
+describe("dev", () => {
+  let root
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "inglorious-capacitor-dev-"))
+    writeFileSync(path.join(root, "package.json"), "{}")
+    writeFileSync(
+      path.join(root, "capacitor.config.json"),
+      JSON.stringify(CAPACITOR_CONFIG),
+    )
+  })
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it("serves Vite on the network and runs the app against it", async () => {
+    buildWebDir(root)
+    const spawn = fakeSpawn()
+
+    const code = await dev({
+      root,
+      platform: "ios",
+      args: ["--target", "ABC"],
+      spawn,
+      isReady: async () => true,
+    })
+
+    expect(code).toBe(0)
+    expect(spawn.calls).toEqual([
+      ["vite", ["--host", "--port", "5173", "--strictPort"]],
+      [
+        "cap",
+        ["run", "ios", "--live-reload", "--port", "5173", "--target", "ABC"],
+      ],
+    ])
+    expect(spawn.children[0].kill).toHaveBeenCalled()
+  })
+
+  it("builds the web app first when it was never built", async () => {
+    const spawn = fakeSpawn()
+
+    await dev({
+      root,
+      platform: "android",
+      port: 3000,
+      spawn,
+      isReady: async () => true,
+    })
+
+    expect(
+      spawn.calls.map(([command, args]) => `${command} ${args[0]}`),
+    ).toEqual(["vite build", "vite --host", "cap run"])
+  })
+
+  it("stops the dev server when the app fails", async () => {
+    buildWebDir(root)
+    const spawn = fakeSpawn({ cap: 1 })
+
+    await expect(
+      dev({ root, platform: "android", spawn, isReady: async () => true }),
+    ).rejects.toThrow("exited with 1")
+    expect(spawn.children[0].kill).toHaveBeenCalled()
+  })
+
+  it("refuses an unknown platform", async () => {
+    await expect(dev({ root, platform: "web" })).rejects.toThrow("Usage")
+  })
+})
+
+function buildWebDir(root) {
+  mkdirSync(path.join(root, "dist"))
+  writeFileSync(path.join(root, "dist", "index.html"), "")
+}
+
+function fakeSpawn(exitCodes = {}) {
+  const spawn = (command, args) => {
+    spawn.calls.push([command, args])
+    const child = Object.assign(new EventEmitter(), { kill: vi.fn() })
+    spawn.children.push(child)
+    const isServer = command === "vite" && args[0] === "--host"
+    if (!isServer) setTimeout(() => child.emit("exit", exitCodes[command] ?? 0))
+    return child
+  }
+  spawn.calls = []
+  spawn.children = []
+  return spawn
+}

package/src/dev/index.js

@@ -0,0 +1,101 @@
+import { spawn as nodeSpawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+
+import { readSettings } from "../config.js"
+
+export const DEV_PORT = 5173
+const PLATFORMS = ["ios", "android"]
+const SUCCESS = 0
+const READY_POLL_MS = 250
+const READY_TIMEOUT_MS = 30_000
+
+/**
+ * Runs the app on a phone or emulator against the Vite dev server on this
+ * computer, so every saved file reloads on the device. Vite listens on the
+ * local network and `cap run --live-reload` points the native app at it;
+ * stopping either stops both, and Capacitor restores the native config.
+ *
+ * @param {{ root?: string, platform: string, port?: number, args?: string[], spawn?: typeof nodeSpawn, isReady?: (url: string) => Promise<boolean> }} options
+ *   `args` go to `cap run`, such as `--target <id>`.
+ * @returns {Promise<number>} The exit code of `cap run`.
+ */
+export async function dev({
+  root = process.cwd(),
+  platform,
+  port = DEV_PORT,
+  args = [],
+  spawn = nodeSpawn,
+  isReady = respondsAt,
+}) {
+  if (!PLATFORMS.includes(platform)) {
+    throw new Error(`Usage: inglorious-capacitor dev <ios|android>`)
+  }
+
+  const { webDir } = await readSettings(root, {})
+  if (!existsSync(path.join(root, webDir, "index.html"))) {
+    await run(spawn, "vite", ["build"], root)
+  }
+
+  const commands = devCommands({ platform, port, args })
+  const server = spawn(...commands.server, { cwd: root, stdio: "inherit" })
+  try {
+    await waitFor(() => isReady(`http://localhost:${port}`))
+    const ignoreInterrupt = () => {}
+    process.on("SIGINT", ignoreInterrupt)
+    try {
+      return await run(spawn, ...commands.app, root)
+    } finally {
+      process.off("SIGINT", ignoreInterrupt)
+    }
+  } finally {
+    server.kill()
+  }
+}
+
+/**
+ * The two processes `dev` starts.
+ *
+ * @param {{ platform: string, port: number, args: string[] }} options
+ */
+export function devCommands({ platform, port, args }) {
+  return {
+    server: ["vite", ["--host", "--port", String(port), "--strictPort"]],
+    app: [
+      "cap",
+      ["run", platform, "--live-reload", "--port", String(port), ...args],
+    ],
+  }
+}
+
+function run(spawn, command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" })
+    child.on("error", reject)
+    child.on("exit", (code) => {
+      if (code)
+        reject(new Error(`${command} ${args.join(" ")} exited with ${code}`))
+      else resolve(SUCCESS)
+    })
+  })
+}
+
+async function waitFor(check) {
+  const deadline = Date.now() + READY_TIMEOUT_MS
+  while (!(await check())) {
+    if (Date.now() > deadline) {
+      throw new Error("The dev server didn't start in time")
+    }
+    await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS))
+  }
+}
+
+async function respondsAt(url) {
+  try {
+    await fetch(url)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/index.js

@@ -1,4 +1,5 @@
 export { assets } from "./assets/index.js"
 export { readSettings } from "./config.js"
 export { configure } from "./configure/index.js"
+export { dev } from "./dev/index.js"
 export { listingAssets } from "./listing-assets/index.js"

package/types/index.d.ts

@@ -69,6 +69,8 @@ export interface ProjectSettings {
   root: string
   appId: string
   appName: string
+  /** The built web app, from the Capacitor config. */
+  webDir: string
   appLinks: Required<NonNullable<NativeConfig["appLinks"]>> | null
   ios: {
     teamId: string | null
@@ -185,3 +187,18 @@ export declare function assets(options?: {
   root?: string
   platforms?: ("ios" | "android")[]
 }): Promise<void>
+
+/**
+ * Runs the app on a device or emulator with live reload: Vite listens on the
+ * local network and `cap run --live-reload` points the app at it. Builds the
+ * web app first if it was never built.
+ * @returns The exit code of `cap run`.
+ */
+export declare function dev(options: {
+  root?: string
+  platform: "ios" | "android"
+  /** Defaults to 5173. */
+  port?: number
+  /** More options for `cap run`, such as `["--target", "<id>"]`. */
+  args?: string[]
+}): Promise<number>