@inglorious/create-app 1.7.1 → 1.8.0

package/bin/lib/firebase.js

@@ -0,0 +1,177 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import { FIRST_ITEM_INDEX } from "./constants.js"
+import { copyDir } from "./file.js"
+
+const MIGRATION_STAMP_LENGTH = 14
+const FIRST_NUMBER = 1
+
+/**
+ * Adds what analytics and push need outside src/: the service worker, the
+ * Supabase side of push, the hook that keeps native apps from measuring before
+ * consent, and the setup steps in the README.
+ *
+ * @param {string} targetDir
+ * @param {object} pkg - The package.json being built; scripts are added.
+ * @param {object} options
+ * @param {string} options.templatesRoot
+ * @param {boolean} options.analytics
+ * @param {boolean} options.push
+ * @param {boolean} options.mobile
+ */
+export function addFirebaseSupport(targetDir, pkg, options) {
+  const { templatesRoot, analytics, push, mobile } = options
+  pkg.scripts ??= {}
+
+  if (push) {
+    copyDir(path.join(templatesRoot, "features/push"), targetDir)
+    stampMigration(targetDir)
+    pkg.scripts["vault:push"] = "node scripts/push-vault-secrets.mjs"
+    keepSupabaseOutOfTypeScript(targetDir)
+  }
+
+  if (analytics && mobile) {
+    copyDir(path.join(templatesRoot, "features/analytics"), targetDir)
+    pkg.scripts["capacitor:sync:after"] =
+      "node scripts/analytics-off-native.mjs"
+  }
+
+  appendSetupToReadme(targetDir, options)
+}
+
+// The Deno function is in no TS project, and Supabase's typings do not compile.
+function keepSupabaseOutOfTypeScript(targetDir) {
+  replaceInFile(
+    path.join(targetDir, "eslint.config.ts"),
+    "defineConfig([\n",
+    'defineConfig([\n  { ignores: ["supabase/"] },\n',
+  )
+  replaceInFile(
+    path.join(targetDir, "tsconfig.app.json"),
+    '"noEmit": true,',
+    '"noEmit": true,\n    "skipLibCheck": true,',
+  )
+}
+
+function replaceInFile(file, search, replacement) {
+  if (!fs.existsSync(file)) return
+  fs.writeFileSync(
+    file,
+    fs.readFileSync(file, "utf-8").replace(search, replacement),
+  )
+}
+
+function stampMigration(targetDir) {
+  const migrations = path.join(targetDir, "supabase/migrations")
+  const stamp = new Date()
+    .toISOString()
+    .replace(/\D/g, "")
+    .slice(FIRST_ITEM_INDEX, MIGRATION_STAMP_LENGTH)
+  fs.renameSync(
+    path.join(migrations, "push.sql"),
+    path.join(migrations, `${stamp}_push.sql`),
+  )
+}
+
+function appendSetupToReadme(targetDir, { analytics, push, mobile }) {
+  const readmePath = path.join(targetDir, "README.md")
+  if (!fs.existsSync(readmePath)) return
+
+  const sections = [firebaseSection({ analytics, push, mobile })]
+  if (analytics) sections.push(analyticsSection(mobile))
+  if (push) sections.push(pushSection(mobile))
+
+  const readme = fs.readFileSync(readmePath, "utf-8")
+  fs.writeFileSync(
+    readmePath,
+    `${readme.trimEnd()}${EOL}${EOL}${sections.join(EOL + EOL)}${EOL}`,
+  )
+}
+
+function firebaseSection({ analytics, push, mobile }) {
+  const steps = [
+    "Create a project in the [Firebase console](https://console.firebase.google.com) and add a web app to it.",
+    "Copy `.env.example` to `.env.local` and fill it in from Project settings → General → your web app. These values end up in the built app, so they are not secret.",
+  ]
+  if (analytics) {
+    steps.push(
+      "`VITE_FIREBASE_MEASUREMENT_ID` is the web app's `measurementId`. Do not paste Google's `gtag.js` snippet into `index.html`: it would start before anyone agreed.",
+    )
+  }
+  if (push) {
+    steps.push(
+      "`VITE_FIREBASE_VAPID_KEY` is the public half of a Web Push key pair, from Project settings → Cloud Messaging → Web configuration.",
+    )
+  }
+  if (mobile) {
+    steps.push(
+      "Add an Android and an iOS app too, then put `google-services.json` in `android/app/` and add `GoogleService-Info.plist` to the App target in Xcode, once `pnpm mobile:init:android` and `pnpm mobile:init:ios` have created the native projects. iOS needs some more setup: see the [Capacitor Firebase plugins](https://github.com/capawesome-team/capacitor-firebase).",
+    )
+  }
+  return `## Firebase Setup
+
+${numbered(steps)}`
+}
+
+function analyticsSection(mobile) {
+  const native = mobile
+    ? `
+
+The native apps must start with collection off, or they measure from launch. \`scripts/analytics-off-native.mjs\` writes that setting into the native projects after every \`cap sync\`.`
+    : ""
+  return `## Analytics
+
+Usage is measured with Google Analytics for Firebase, and only for people who said yes: until then, no analytics code loads. Check that your privacy policy covers it, naming Google as the processor.
+
+Page views follow the router by themselves. The app's own events go through the entity, and are dropped without consent:
+
+\`\`\`js
+api.notify("#analytics:analyticsTrack", { name: "sign_up" })
+\`\`\`
+
+To let people change their answer, for example from a settings page, notify \`#analytics:analyticsAsk\` to bring the prompt back.${native}`
+}
+
+function pushSection(mobile) {
+  const devices = mobile ? "the PWA and the native apps" : "the PWA"
+  return `## Push Notifications
+
+Pushes reach ${devices} through Firebase Cloud Messaging. Supabase keeps each device's token and sends: inserting a row in \`notifications\` is what sends a push.
+
+\`\`\`sql
+insert into public.notifications (user_id, title, body, url)
+values ('<user id>', 'Hello', 'You have a new message', '/');
+\`\`\`
+
+The permission prompt appears once someone signs in with Supabase Auth, so the app needs a sign-in screen. To sign out, call \`signOut\` from \`src/api/push\`, which deletes the device's token first.
+
+To set it up, with the [Supabase CLI](https://supabase.com/docs/guides/cli) installed:
+
+${numbered([
+  "In the Firebase console, go to Project settings → Service accounts → Generate new private key. The file is a real secret: never commit it.",
+  "In the Google Cloud console, give that service account the **Firebase Cloud Messaging API Admin** role. The similarly named Firebase Cloud Messaging Admin cannot send.",
+  "Run `supabase init` here, then `supabase start` to try it locally, with the file's JSON on one line as `FCM_SERVICE_ACCOUNT` in `supabase/functions/.env`. `supabase status` gives the values of `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`.",
+])}
+
+To deploy:
+
+\`\`\`bash
+supabase link --project-ref <your project ref>
+supabase db push
+supabase secrets set FCM_SERVICE_ACCOUNT="$(cat path/to/service-account.json)"
+supabase functions deploy push-notify
+pnpm vault:push
+\`\`\`
+
+\`pnpm vault:push\` tells the database how to reach the function. It stores the project's legacy \`service_role\` key in Vault, which is the key \`push-notify\` can read a role from.
+
+A browser's service worker only exists in a build, so try web pushes with \`pnpm build && pnpm preview\`.`
+}
+
+function numbered(steps) {
+  return steps
+    .map((step, index) => `${FIRST_NUMBER + index}. ${step}`)
+    .join("\n")
+}

package/bin/lib/imports.js

@@ -1,8 +1,3 @@
-// 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 })
 
 /**
@@ -34,15 +29,12 @@ function sortImports(lines) {
       (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(/^[./]*\.$/, "$&/")
@@ -57,7 +49,6 @@ 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

@@ -14,8 +14,6 @@ export function addMobileSupport(targetDir, pkg, projectName) {
   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"
@@ -124,9 +122,6 @@ export default config
 `
 }
 
-// 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

package/bin/lib/prompts.js

@@ -0,0 +1,311 @@
+import { importBlock } from "./imports.js"
+import { LINE_WIDTH } from "./source.js"
+
+const FIREBASE_CONFIG_KEYS = {
+  apiKey: "VITE_FIREBASE_API_KEY",
+  projectId: "VITE_FIREBASE_PROJECT_ID",
+  messagingSenderId: "VITE_FIREBASE_MESSAGING_SENDER_ID",
+  appId: "VITE_FIREBASE_APP_ID",
+}
+
+/**
+ * The source files of the analytics and push prompts. They are lit-html in
+ * every syntax: src/main renders them next to the app, whatever it is written
+ * in.
+ *
+ * @param {{ analytics: boolean, push: boolean, ui: boolean, i18n: boolean, ext: string, isTypeScript: boolean, projectName: string }} app
+ * @returns {Record<string, string>} Sources by file path.
+ */
+export function promptFiles(app) {
+  const files = {
+    [`src/api/firebase.${app.ext}`]: firebaseSource(app),
+    [`src/common/prompt.${app.ext}`]: promptSource(app),
+  }
+  if (app.analytics) {
+    files[`src/types/analytics.${app.ext}`] = analyticsSource(app)
+  }
+  if (app.push) {
+    files[`src/api/supabase.${app.ext}`] = supabaseSource()
+    files[`src/api/push.${app.ext}`] = pushSource(app)
+    files[`src/types/push-prompt.${app.ext}`] = pushPromptSource(app)
+  }
+  return files
+}
+
+export function envExample(app) {
+  const keys = Object.values(FIREBASE_CONFIG_KEYS)
+  if (app.analytics) keys.push("VITE_FIREBASE_MEASUREMENT_ID")
+  if (app.push) {
+    keys.push(
+      "VITE_FIREBASE_VAPID_KEY",
+      "VITE_SUPABASE_URL",
+      "VITE_SUPABASE_ANON_KEY",
+    )
+  }
+  return keys.map((key) => `${key}=`).join("\n") + "\n"
+}
+
+function firebaseSource(app) {
+  const entries = Object.entries(FIREBASE_CONFIG_KEYS).map(
+    ([key, env]) => `  ${key}: import.meta.env.${env},`,
+  )
+  if (app.analytics) {
+    entries.push(
+      "  measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID,",
+    )
+  }
+  return `export const firebaseConfig = {
+${entries.join("\n")}
+}
+`
+}
+
+function promptSource(app) {
+  const props = app.isTypeScript
+    ? `interface PromptProps {
+  message: string
+  askLabel: string
+  declineLabel: string
+  onAsk: () => void
+  onDecline: () => void
+}
+
+`
+    : ""
+  const annotation = app.isTypeScript ? ": PromptProps" : ""
+  const params = `{ message, askLabel, declineLabel, onAsk, onDecline }${annotation}`
+  const signature =
+    `  render(${params}) {`.length <= LINE_WIDTH
+      ? `  render(${params}) {`
+      : `  render({
+    message,
+    askLabel,
+    declineLabel,
+    onAsk,
+    onDecline,
+  }${annotation}) {`
+
+  if (app.ui) {
+    return `${importBlock(
+      promptImports(app, [
+        'import { Button } from "@inglorious/ui/button"',
+        'import { Flex } from "@inglorious/ui/flex"',
+        'import { Snackbar } from "@inglorious/ui/snackbar"',
+      ]),
+    )}
+
+${props}export const Prompt = {
+${signature}
+    return Snackbar.render({
+      isOpen: true,
+      position: "bottom-center",
+      message,
+      action: Flex.render({
+        direction: "row",
+        align: "center",
+        gap: "sm",
+        children: [
+          Button.render({
+            children: askLabel,
+            color: "primary",
+            size: "sm",
+            onClick: onAsk,
+          }),
+          Button.render({
+            children: declineLabel,
+            variant: "ghost",
+            size: "sm",
+            onClick: onDecline,
+          }),
+        ],
+      }),
+    })
+  },
+}
+${renderPromptsSource(app)}`
+  }
+
+  return `${importBlock(promptImports(app, []))}
+
+${props}export const Prompt = {
+${signature}
+    return html\`<div class="app-prompt">
+      <p>\${message}</p>
+      <button @click=\${onAsk}>\${askLabel}</button>
+      <button @click=\${onDecline}>\${declineLabel}</button>
+    </div>\`
+  },
+}
+${renderPromptsSource(app)}`
+}
+
+function promptImports(app, imports) {
+  return [
+    ...imports,
+    'import { html } from "@inglorious/web"',
+    ...(app.isTypeScript ? ['import type { AppApi } from "../../types"'] : []),
+  ]
+}
+
+// Prettier moves a value to its own line when the property would not fit.
+function prop(name, value, indent) {
+  const line = `${indent}${name}: ${value},`
+  if (line.length <= LINE_WIDTH) return line
+  return `${indent}${name}:\n${indent}  ${value},`
+}
+
+function renderPromptsSource(app) {
+  const annotation = app.isTypeScript ? ": AppApi" : ""
+  const prompts = [
+    ...(app.analytics ? ['${api.render("analytics")}'] : []),
+    ...(app.push ? ['${api.render("pushPrompt")}'] : []),
+  ]
+  return `
+export function renderPrompts(api${annotation}) {
+  return html\`${prompts.join(" ")}\`
+}
+`
+}
+
+function analyticsSource(app) {
+  const imports = [
+    'import { firebaseAnalytics } from "@inglorious/firebase/analytics"',
+    'import { createAnalytics } from "@inglorious/web/analytics"',
+    'import { when } from "@inglorious/web/directives/when"',
+    'import { firebaseConfig } from "../api/firebase"',
+    'import { Prompt } from "../common/prompt"',
+  ]
+  if (app.i18n) imports.push('import { t } from "../i18n"')
+  if (app.isTypeScript) {
+    imports.push(
+      'import type { AppAnalyticsEntity, AppApi } from "../../types"',
+    )
+  }
+  const label = labelFor(app)
+  const params = app.isTypeScript
+    ? "entity: AppAnalyticsEntity, api: AppApi"
+    : "entity, api"
+
+  return `${importBlock(imports)}
+
+export const Analytics = {
+  ...createAnalytics({
+    adapter: firebaseAnalytics({ firebase: firebaseConfig }),
+    consentKey: "${app.projectName}-analytics-consent",
+  }),
+
+  render(${params}) {
+    return when(entity.isAsking, () =>
+      Prompt.render({
+${prop("message", label("analytics.prompt", "May we measure how you use this app? It helps us make it better."), "        ")}
+${prop("askLabel", label("analytics.accept", "Allow"), "        ")}
+${prop("declineLabel", label("analytics.decline", "No thanks"), "        ")}
+        onAsk: () => api.notify(\`#\${entity.id}:analyticsConsent\`, true),
+        onDecline: () => api.notify(\`#\${entity.id}:analyticsConsent\`, false),
+      }),
+    )
+  },
+}
+`
+}
+
+function supabaseSource() {
+  return `import { createClient } from "@supabase/supabase-js"
+
+export const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+)
+`
+}
+
+function pushSource(app) {
+  const token = app.isTypeScript ? "token: string" : "token"
+  const platform = app.isTypeScript ? "platform: string" : "platform"
+  return `import { firebasePush } from "@inglorious/firebase/push"
+
+import { firebaseConfig } from "./firebase"
+import { supabase } from "./supabase"
+
+export const push = firebasePush({
+  firebase: firebaseConfig,
+  vapidKey: import.meta.env.VITE_FIREBASE_VAPID_KEY,
+  saveToken,
+  deleteToken,
+  tokenKey: "${app.projectName}-push-token",
+})
+
+async function saveToken(${token}, ${platform}) {
+  const { error } = await supabase.rpc("save_push_token", {
+    p_token: token,
+    p_platform: platform,
+  })
+  if (error) throw error
+}
+
+async function deleteToken(${token}) {
+  const { error } = await supabase
+    .from("push_tokens")
+    .delete()
+    .eq("token", token)
+  if (error) throw error
+}
+
+// The token goes first: only its signed-in user may delete it.
+export async function signOut() {
+  await push.unregister().catch(() => {})
+  await supabase.auth.signOut()
+}
+`
+}
+
+function pushPromptSource(app) {
+  const imports = [
+    'import { when } from "@inglorious/web/directives/when"',
+    'import { createPushPrompt } from "@inglorious/web/push"',
+    'import { push } from "../api/push"',
+    'import { Prompt } from "../common/prompt"',
+  ]
+  if (app.i18n) imports.push('import { t } from "../i18n"')
+  if (app.isTypeScript) {
+    imports.push(
+      'import type { AppApi, AppPushPromptEntity } from "../../types"',
+    )
+  }
+  const label = labelFor(app)
+  const params = app.isTypeScript
+    ? "entity: AppPushPromptEntity, api: AppApi"
+    : "entity, api"
+  const isShown = app.analytics
+    ? `entity.isOpen && !api.getEntity("analytics")${app.isTypeScript ? "!" : ""}.isAsking`
+    : "entity.isOpen"
+  const open = app.analytics
+    ? "    // One question at a time, the consent first.\n"
+    : ""
+
+  return `${importBlock(imports)}
+
+export const PushPrompt = {
+  ...createPushPrompt({
+    adapter: push,
+    declineKey: "${app.projectName}-push-declined",
+  }),
+
+  render(${params}) {
+${open}    return when(${isShown}, () =>
+      Prompt.render({
+        message: ${label("push.prompt", "Turn on push notifications?")},
+        askLabel: ${label("push.ask", "Notify me")},
+        declineLabel: ${label("push.decline", "Not now")},
+        onAsk: () => api.notify(\`#\${entity.id}:pushAsk\`),
+        onDecline: () => api.notify(\`#\${entity.id}:pushDecline\`),
+      }),
+    )
+  },
+}
+`
+}
+
+function labelFor(app) {
+  return (key, text) => (app.i18n ? `t("${key}")` : JSON.stringify(text))
+}

package/bin/lib/pwa.js

@@ -9,7 +9,12 @@ import {
 } from "./constants.js"
 import { findMainPath, findViteConfigPath, injectAfterImport } from "./file.js"
 
-export function addPwaSupport(targetDir, pkg, projectName) {
+export function addPwaSupport(
+  targetDir,
+  pkg,
+  projectName,
+  { push = false } = {},
+) {
   pkg.devDependencies ??= {}
   pkg.devDependencies["vite-plugin-pwa"] = VITE_PLUGIN_PWA_VERSION
   pkg.devDependencies["@vite-pwa/assets-generator"] =
@@ -19,7 +24,7 @@ export function addPwaSupport(targetDir, pkg, projectName) {
   const publicDir = path.join(targetDir, "public")
   fs.mkdirSync(publicDir, { recursive: true })
 
-  injectPwaPluginConfig(targetDir, projectName)
+  injectPwaPluginConfig(targetDir, projectName, { push })
   writePwaRegistration(targetDir)
   injectServiceWorkerRegistration(targetDir)
 }
@@ -40,7 +45,11 @@ export function injectServiceWorkerRegistration(targetDir) {
   fs.writeFileSync(mainPath, main)
 }
 
-export function injectPwaPluginConfig(targetDir, projectName) {
+export function injectPwaPluginConfig(
+  targetDir,
+  projectName,
+  { push = false } = {},
+) {
   const viteConfigPath = findViteConfigPath(targetDir)
 
   if (!viteConfigPath) {
@@ -50,8 +59,6 @@ export function injectPwaPluginConfig(targetDir, projectName) {
   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")
@@ -62,12 +69,11 @@ export function injectPwaPluginConfig(targetDir, projectName) {
   }
 
   if (!viteConfig.includes("VitePWA(")) {
-    // One plugin per line, as Prettier prints a list this long.
     viteConfig = viteConfig.replace(
       /plugins: \[(.*)\],/,
       (_, plugins) =>
         `plugins: [${EOL}${[
-          createVitePwaConfig(projectName),
+          createVitePwaConfig(projectName, { push }),
           ...splitPlugins(plugins),
         ]
           .map((plugin) => `    ${plugin},`)
@@ -91,9 +97,6 @@ export function writePwaRegistration(targetDir) {
   fs.writeFileSync(pwaPath, createPwaRegistrationSource(extension))
 }
 
-// The worker waits for the SKIP_WAITING message `watchPwaUpdate` sends: on
-// its own, a new version would wait for every tab of the app to close, which
-// for a PWA installed on a phone is never.
 export function createPwaRegistrationSource(extension) {
   const registration = `import { isNative } from "@inglorious/web/mobile"
 import { watchPwaUpdate } from "@inglorious/web/pwa"
@@ -118,7 +121,13 @@ ${registration}`
   return registration
 }
 
-export function createVitePwaConfig(projectName) {
+export function createVitePwaConfig(projectName, { push = false } = {}) {
+  const workbox = push
+    ? `
+      workbox: {
+        importScripts: ["sw-push.js"],
+      },`
+    : ""
   return `VitePWA({
       injectRegister: false,
       registerType: "prompt",
@@ -134,12 +143,10 @@ export function createVitePwaConfig(projectName) {
         background_color: "#ffffff",
         display: "standalone",
         start_url: "/",
-      },
+      },${workbox}
     })`
 }
 
-// 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
@@ -158,8 +165,6 @@ function splitPlugins(source) {
   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)