@flaredev/cli 0.12.0 → 0.12.2

package/dist/index.js

@@ -204,10 +204,12 @@ var PROVIDERS = {
     hint: { both: "a CDN with an uploader" },
     stacks: ["cloudflare", "next"],
     vars: {
-      cloudflare: [{ name: "UPLOADTHING_TOKEN" }, { name: "UPLOADTHING_APP_ID", example: "a1b2c3d4e5" }],
-      next: [{ name: "UPLOADTHING_TOKEN" }, { name: "UPLOADTHING_APP_ID", example: "a1b2c3d4e5" }]
+      // One variable, not two. The token is base64 JSON carrying the app id, so the
+      // driver reads the id out of it rather than asking for it a second time.
+      cloudflare: [{ name: "UPLOADTHING_TOKEN" }],
+      next: [{ name: "UPLOADTHING_TOKEN" }]
     },
-    where: "UploadThing dashboard \u2192 your app \u2192 API Keys (the app id is in the same place)",
+    where: "UploadThing dashboard \u2192 your app \u2192 API Keys",
     console: "https://uploadthing.com/dashboard",
     docs: `${DOCS}/uploadthing/`,
     install: "uploadthing",
@@ -276,13 +278,17 @@ function storageEnvExample(name, stack) {
   lines.push("", `# Or switch driver: ${others.join(", ")} \u2014 see the guide above.`, "");
   return lines.join("\n");
 }
-function storageSetupSteps(name, stack) {
+function storageSetupSteps(name, stack, options2 = {}) {
   const provider = STORAGE_PROVIDERS[name];
   const vars = storageVars(name, stack);
   const steps = [];
-  if (provider.install) steps.push(`Install its SDK: ${provider.install}`);
+  const readyLocally = options2.local !== false && vars.length > 0 && vars.every((variable) => variable.local);
   if (vars.length > 0 && provider.console) {
-    steps.push(`Get ${vars.map((variable) => variable.name).join(", ")} from ${provider.where ?? provider.console}`);
+    if (readyLocally) {
+      steps.push(`Works locally as it is. When you deploy, replace ${vars.map((variable) => variable.name).join(", ")}:`);
+    } else {
+      steps.push(`Get ${vars.map((variable) => variable.name).join(", ")} from ${provider.where ?? provider.console}`);
+    }
     steps.push(provider.console);
   }
   if (provider.caveat) steps.push(provider.caveat);
@@ -365,8 +371,13 @@ var NEXT_DEPENDENCIES = {
   // protocol. Vercel refuses to build it. A pin is only worth having if it is moved when
   // one of these lands, so treat a critical against this line as a release of its own.
   next: "16.3.8",
-  "@prisma/client": "7.10.0",
-  "@prisma/adapter-pg": "7.10.0",
+  // Prisma 7, pinned exactly and deliberately. `prisma@latest` is 8.0.0-rc — a release
+  // candidate — and Prisma's own update notifier prints "npm i @prisma/client@latest"
+  // inside `prisma migrate` output, so an app that follows that advice lands on a
+  // prerelease. The three move together or not at all; a client newer than the CLI that
+  // generated it is the mismatch that shows up as a runtime error, not a build one.
+  "@prisma/client": "7.10.1",
+  "@prisma/adapter-pg": "7.10.1",
   pg: "^8.16.3",
   "@upstash/redis": "^1.36.0",
   "@better-auth/prisma-adapter": "1.7.17",
@@ -375,7 +386,9 @@ var NEXT_DEPENDENCIES = {
   dotenv: "^17.2.3"
 };
 var NEXT_DEV_DEPENDENCIES = {
-  prisma: "7.10.0",
+  // Matches @prisma/client and @prisma/adapter-pg above. See the note there before
+  // moving it: the newest 7.x, not `latest`, which is an 8.0 release candidate.
+  prisma: "7.10.1",
   // Runs seeds: the generated Prisma client is TypeScript a bundler compiles.
   tsx: "^4.23.13",
   // `flare deploy` and `npm run deploy`. Local rather than global, so the deploy works
@@ -388,6 +401,9 @@ var NEXT_DEV_DEPENDENCIES = {
   tailwindcss: "^4.3.3",
   typescript: "~5.9.3"
 };
+var STORAGE_DEPENDENCIES = {
+  uploadthing: "^7.7.4"
+};
 var CLOUDFLARE_ONLY = [
   "wrangler.jsonc",
   "vite.config.ts",
@@ -502,7 +518,15 @@ function installArgs(pm) {
 }
 
 // src/commands/create.ts
-var ALLOW_BUILDS = ["'@prisma/engines': false", "esbuild: true", "prisma: true", "sharp: false", "workerd: true"].map((line) => `  ${line}`).join("\n");
+var SEED_ADMIN = { email: "admin@example.com", password: "Password", name: "Admin" };
+var ALLOW_BUILDS = [
+  "'@prisma/engines': false",
+  "esbuild: true",
+  "msgpackr-extract: false",
+  "prisma: true",
+  "sharp: false",
+  "workerd: true"
+].map((line) => `  ${line}`).join("\n");
 function toAppName(dir) {
   const name = basename(resolve2(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
   if (!name) throw new Error(`Cannot derive an app name from "${dir}". Use letters, digits, and dashes.`);
@@ -574,12 +598,22 @@ storage/
     // Which stack this app targets. `flare gen` reads it; don't change it by hand.
     flare: { stack },
     scripts: stack === "next" ? {
+      // Prisma 7 generates its client into lib/generated/prisma, which is
+      // git-ignored and therefore absent from every fresh checkout — including
+      // the one `create` has just written. Without this the first `dev` fails on
+      // `Can't resolve './generated/prisma/client'` before serving a page, and
+      // so does `flare user:add`, which imports lib/db. postinstall rather than a
+      // step in `dev`, so a teammate cloning the repo is covered by the same line.
+      postinstall: "prisma generate",
       dev: "next dev",
       build: "prisma generate && next build",
       start: "next start",
       deploy: "vercel deploy --prod",
       "db:generate": "prisma generate",
       "db:migrate": "prisma migrate dev",
+      // An account to sign in with, so the app is reachable the moment the tables
+      // exist. Safe to run twice: --skip-existing makes a second run a no-op.
+      "db:seed": `flare user:add ${SEED_ADMIN.email} --password ${SEED_ADMIN.password} --name ${SEED_ADMIN.name} --role admin --skip-existing`,
       "db:studio": "prisma studio"
     } : {
       dev: "flare dev",
@@ -592,7 +626,10 @@ storage/
     },
     dependencies: {
       "@flaredev/core": flarePackageSpec("core", dir, packageManager),
-      ...stack === "next" ? { ...uiOnly, ...shared, ...NEXT_DEPENDENCIES } : APP_DEPENDENCIES
+      ...stack === "next" ? { ...uiOnly, ...shared, ...NEXT_DEPENDENCIES } : APP_DEPENDENCIES,
+      // The chosen provider's SDK, where it has one, so the first upload works without
+      // a second install.
+      ...storage in STORAGE_DEPENDENCIES ? { [storage]: STORAGE_DEPENDENCIES[storage] } : {}
     },
     devDependencies: {
       "@flaredev/cli": flarePackageSpec("cli", dir, packageManager),
@@ -651,9 +688,15 @@ function copyLockfile(packageManager, dir, stack) {
 function printNextSteps(result, installed) {
   const rel = relative(process.cwd(), result.dir) || ".";
   const pm = result.packageManager;
+  const database = result.stack === "next" ? [
+    ["docker compose up -d", "Postgres, on the address .env already has"],
+    [`${pm} run db:migrate`, "create the tables"],
+    [`${pm} run db:seed`, "an account to sign in with"]
+  ] : [];
   const commands = [
     [`cd ${rel}`, "your new app"],
     ...installed ? [] : [[`${pm} install`, "dependencies first"]],
+    ...database,
     [`${pm} run dev`, "http://localhost:3000"],
     ["npx flare gen resource Contact", "a table, API and admin screens"],
     ["npx flare seed:resource Contact 1000", "fill it with sample rows"]
@@ -661,10 +704,20 @@ function printNextSteps(result, installed) {
   const width = Math.max(...commands.map(([command]) => command.length)) + 2;
   const steps = commands.map(([command, note2]) => `${pc.cyan(command.padEnd(width))}${pc.dim(note2)}`);
   prompts.note(steps.join("\n"), "Next");
-  const storage = storageSetupSteps(result.storage, result.stack);
+  const storage = storageSetupSteps(result.storage, result.stack, { local: true });
   if (storage.length > 0) {
     prompts.note(storage.map((line) => line.startsWith("http") ? pc.cyan(line) : line).join("\n"), `Uploads \xB7 ${result.storage}`);
   }
+  if (result.stack === "next") {
+    prompts.note(
+      [
+        `${pc.cyan(SEED_ADMIN.email)}  ${pc.dim("\xB7")}  ${pc.cyan(SEED_ADMIN.password)}`,
+        "",
+        pc.dim(`Made by ${pm} run db:seed, as an admin. Change it before this app is anywhere but your machine.`)
+      ].join("\n"),
+      "Sign in with"
+    );
+  }
   prompts.outro(`${pc.bold(result.name)} is ready ${pc.dim("\xB7")} ${pc.cyan("https://flare-docs.codetotech.com/start/quickstart/")}`);
 }
 
@@ -2882,6 +2935,51 @@ function checkTemplateVersion(installed, cli) {
     fix: "Update the app's dependencies, then `flare update` to take the template changes you want."
   } : { check: "Flare version", verdict: "warn", detail: `app has @flaredev/core ${installed}, which is newer than this CLI (${cli}).`, fix: "Update the CLI." };
 }
+function installedVersion(appRoot, name) {
+  const path = join14(appRoot, "node_modules", ...name.split("/"), "package.json");
+  if (!existsSync15(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync10(path, "utf8")).version;
+  } catch {
+    return void 0;
+  }
+}
+var PRISMA_PACKAGES = ["prisma", "@prisma/client", "@prisma/adapter-pg"];
+function checkPrismaVersions(versions) {
+  const found = Object.entries(versions).filter(([, version]) => version !== void 0);
+  if (found.length === 0) {
+    return { check: "Prisma", verdict: "skip", detail: "Prisma is not installed yet.", fix: "Install dependencies." };
+  }
+  const majors = new Set(found.map(([, version]) => version.split(".")[0]));
+  if (majors.size > 1) {
+    return {
+      check: "Prisma",
+      verdict: "fail",
+      detail: `the Prisma packages disagree on a major: ${found.map(([name, version]) => `${name} ${version}`).join(", ")}.`,
+      fix: "Set all three to the same version. A client the installed CLI did not generate fails on the first query, not at build."
+    };
+  }
+  const [major] = [...majors];
+  if (major !== "7") {
+    const prerelease = found.find(([, version]) => version.includes("-"));
+    return {
+      check: "Prisma",
+      verdict: "fail",
+      detail: `the app is on Prisma ${major}${prerelease ? ` (${prerelease[1]}, a prerelease)` : ""}; Flare generates for 7.`,
+      fix: "Pin prisma, @prisma/client and @prisma/adapter-pg to the same 7.x. `prisma@latest` is an 8.0 release candidate, so ask for the version by number."
+    };
+  }
+  const distinct = new Set(found.map(([, version]) => version));
+  if (distinct.size > 1) {
+    return {
+      check: "Prisma",
+      verdict: "warn",
+      detail: `Prisma 7, but at mixed versions: ${found.map(([name, version]) => `${name} ${version}`).join(", ")}.`,
+      fix: "Match them. They are released together and are only tested together."
+    };
+  }
+  return { check: "Prisma", verdict: "ok", detail: `Prisma ${[...distinct][0]}, all three in step.` };
+}
 function checkRateLimitBackend(declared, configured, stack) {
   if (declared.length === 0) return { check: "Rate limits", verdict: "ok", detail: "none declared." };
   const list2 = declared.map((entry) => `${entry.resource}.${entry.action} ${entry.spec}`).join(", ");
@@ -2918,6 +3016,9 @@ async function diagnose(options2 = {}) {
   }
   findings.push({ check: "Stack", verdict: "ok", detail: stack === "next" ? "Next.js (Prisma, Postgres)." : "Cloudflare (vinext, D1, Drizzle)." });
   findings.push(checkTemplateVersion(installedCoreVersion(appRoot), FLARE_VERSION2));
+  if (stack === "next") {
+    findings.push(checkPrismaVersions(Object.fromEntries(PRISMA_PACKAGES.map((name) => [name, installedVersion(appRoot, name)]))));
+  }
   findings.push(checkEnv(appRoot, stack));
   findings.push(checkBindings(appRoot, stack));
   let resources = [];
@@ -3107,6 +3208,7 @@ ${result.output.trim()}`);
 // src/commands/user-add.ts
 var EMAIL = /^[^\s@'"\\]+@[^\s@'"\\]+\.[^\s@'"\\]+$/;
 var ROLE = /^[a-z][a-z0-9_-]{0,31}$/;
+var KEPT = -1;
 function generatePassword(length = 24) {
   const alphabet = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789";
   const bytes = crypto.getRandomValues(new Uint8Array(length));
@@ -3153,7 +3255,8 @@ async function addUser(email, options2 = {}) {
   const password = options2.password ?? generatePassword();
   const generated = options2.password === void 0;
   const rows = await credentialUserRows({ email: address, password, name: options2.name, role: options2.role });
-  const code = readStack(appRoot) === "next" ? await addOnPrisma(appRoot, rows, log2) : await addOnD1(appRoot, rows, options2, log2);
+  const code = readStack(appRoot) === "next" ? await addOnPrisma(appRoot, rows, log2, options2.skipExisting) : await addOnD1(appRoot, rows, options2, log2);
+  if (code === KEPT) return 0;
   if (code !== 0) return code;
   log2(pc9.green(`\u2714 ${address} can now sign in${options2.role ? ` as ${options2.role}` : ""}.`));
   if (generated) {
@@ -3186,6 +3289,10 @@ async function addOnD1(appRoot, rows, options2, log2) {
 ${existing.output.trim()}`);
   const [found] = extractJson(existing.output);
   if ((found?.results ?? []).length > 0) {
+    if (options2.skipExisting) {
+      log2(pc9.dim(`${rows.user.email} already has an account \u2014 left as it is.`));
+      return KEPT;
+    }
     log2(pc9.red(`${rows.user.email} already has an account.`));
     log2(pc9.dim("To change their role: flare user:role <email> <role>"));
     return 1;
@@ -3195,7 +3302,7 @@ ${existing.output.trim()}`);
 ${result.output.trim()}`);
   return 0;
 }
-async function addOnPrisma(appRoot, rows, log2) {
+async function addOnPrisma(appRoot, rows, log2, skipExisting = false) {
   const runner = join15(appRoot, ".flare-user-add-runner.mts");
   const script = [
     `import "dotenv/config";`,
@@ -3222,6 +3329,10 @@ async function addOnPrisma(appRoot, rows, log2) {
   try {
     const code = await runNode([resolveBin(appRoot, "tsx", "tsx"), runner], appRoot);
     if (code === 3) {
+      if (skipExisting) {
+        log2(pc9.dim(`${rows.user.email} already has an account \u2014 left as it is.`));
+        return KEPT;
+      }
       log2(pc9.red(`${rows.user.email} already has an account.`));
       log2(pc9.dim("To change their role: flare user:role <email> <role>"));
       return 1;
@@ -5948,7 +6059,7 @@ ${problems.map((problem) => `  ${problem}`).join("\n")}`);
     }
     if (renamed.length) {
       log2(`${pc17.cyan("prisma")} migrate dev --name ${name}_rename`);
-      const applied = await runNodeCapturing([prisma, "migrate", "dev", "--skip-generate", "--name", `${name}_rename`], appRoot);
+      const applied = await runNodeCapturing([prisma, "migrate", "dev", "--name", `${name}_rename`], appRoot);
       if (applied.code !== 0) {
         throw new Error(`The rename migration could not be applied:
 ${applied.output.trim()}`);
@@ -7746,7 +7857,7 @@ function createCli() {
       printNextSteps(result, installed);
     }
   );
-  cli.command("gen <generator> [name] [second]", `Generate code. Generators: ${GENERATORS.join(", ")}`).option("--fields <fields>", "resource: fields, e.g. 'name:string, email:string!, status:enum(lead,customer)' (single quotes: bash treats ! in double quotes as history)").option("--group <name>", "resource: sidebar heading to file it under, e.g. Sales").option("--icon <name>", "resource: lucide icon for the sidebar, e.g. users").option("--soft-delete", "resource: keep deleted rows and hide them, with a Trash view in the dashboard").option("--method <verb>", "endpoint: GET (default), POST, PATCH, PUT or DELETE").option("--action <action>", "endpoint: policy action to require (read, create, update, delete)").option("--record", "endpoint: put it under one record, /api/<resource>/[id]/<name>").option("--force", "resource/policy/billing/security: overwrite hand-edited generated blocks").option("--from-schema", "migration: diff the current tables instead of a blank migration (Cloudflare only)").example("flare gen migration add_phone --from-schema         # Cloudflare: diff the Drizzle tables").example("flare gen migration add_phone                       # Next.js: prisma migrate dev, refusing a drop").option("--roles <roles>", "policy: roles allowed to read, create and update, e.g. admin,staff").option("--delete-roles <roles>", "policy: roles allowed to delete (default: the first --roles entry)").option("--own <field>", "policy: confine each user to rows whose field holds their id, e.g. --own userId").option("--own-except <roles>", "policy: roles that see every row despite --own, e.g. admin").option("--provider <provider>", "billing: payment provider (default: stripe)").option("--mode <mode>", "billing: subscriptions (the default; includes one-time checkout)").option("--skip-install", "billing/apikeys: write files without adding the dependency").option("--skip-migration", "billing/security/apikeys: skip generating the schema migration").example("flare gen resource Contact --fields 'name:string, email:string!, company:belongsTo(Company)?'").example("flare gen resource Invoice --fields 'number:string!' --soft-delete   # a delete goes to the Trash").example("flare gen endpoint Order publish --method POST --record").example("flare gen migration backfill_contact_status").example("flare gen migration add_phone_to_contacts --from-schema").example("flare gen policy Invoice --roles admin,staff --delete-roles admin").example("flare gen policy Invoice --roles staff --own userId --own-except admin   # each user sees only their own").example("flare gen billing --provider stripe --mode subscriptions").example("flare gen security").example("flare gen apikeys                                   # API keys for cron jobs, scripts and mobile apps").example("flare gen apikeys                                     # bearer keys for crons, scripts and mobile apps").action(
+  cli.command("gen <generator> [name] [second]", `Generate code. Generators: ${GENERATORS.join(", ")}`).option("--fields <fields>", "resource: fields, e.g. 'name:string, email:string!, status:enum(lead,customer)' (single quotes: bash treats ! in double quotes as history)").option("--group <name>", "resource: sidebar heading to file it under, e.g. Sales").option("--icon <name>", "resource: lucide icon for the sidebar, e.g. users").option("--soft-delete", "resource: keep deleted rows and hide them, with a Trash view in the dashboard").option("--method <verb>", "endpoint: GET (default), POST, PATCH, PUT or DELETE").option("--action <action>", "endpoint: policy action to require (read, create, update, delete)").option("--record", "endpoint: put it under one record, /api/<resource>/[id]/<name>").option("--force", "resource/policy/billing/security: overwrite hand-edited generated blocks").option("--from-schema", "migration: diff the current tables instead of a blank migration; on Next.js, also apply declared renames").example("flare gen migration add_phone --from-schema         # Cloudflare: diff the Drizzle tables").example("flare gen migration add_phone                       # Next.js: prisma migrate dev, refusing a drop").option("--roles <roles>", "policy: roles allowed to read, create and update, e.g. admin,staff").option("--delete-roles <roles>", "policy: roles allowed to delete (default: the first --roles entry)").option("--own <field>", "policy: confine each user to rows whose field holds their id, e.g. --own userId").option("--own-except <roles>", "policy: roles that see every row despite --own, e.g. admin").option("--provider <provider>", "billing: payment provider (default: stripe)").option("--mode <mode>", "billing: subscriptions (the default; includes one-time checkout)").option("--skip-install", "billing/apikeys: write files without adding the dependency").option("--skip-migration", "billing/security/apikeys: skip generating the schema migration").example("flare gen resource Contact --fields 'name:string, email:string!, company:belongsTo(Company)?'").example("flare gen resource Invoice --fields 'number:string!' --soft-delete   # a delete goes to the Trash").example("flare gen endpoint Order publish --method POST --record").example("flare gen migration backfill_contact_status").example("flare gen migration add_phone_to_contacts --from-schema").example("flare gen policy Invoice --roles admin,staff --delete-roles admin").example("flare gen policy Invoice --roles staff --own userId --own-except admin   # each user sees only their own").example("flare gen billing --provider stripe --mode subscriptions").example("flare gen security").example("flare gen apikeys                                   # API keys for cron jobs, scripts and mobile apps").example("flare gen apikeys                                     # bearer keys for crons, scripts and mobile apps").action(
     async (generator, name, second, options2) => {
       if (generator === "billing")
         return genBilling({ provider: options2.provider, mode: options2.mode, force: options2.force, skipInstall: options2.skipInstall, skipMigration: options2.skipMigration });
@@ -7870,9 +7981,11 @@ function createCli() {
   cli.command("sync-types", "Regenerate schema, routes, clients, and validators from resource descriptors; report drift").option("--check", "Change nothing; exit 1 if anything is out of sync (CI)").option("--force", "Overwrite generated blocks that were edited by hand").action(async (options2) => {
     process.exitCode = await syncTypes(options2);
   });
-  cli.command("user:add <email>", "Create an account from the command line (the way in when signup is closed)").option("--role <role>", "Role to give them, e.g. admin").option("--password <password>", "Their password (generated and printed when omitted)").option("--name <name>", "Display name (default: the part before the @)").option("--remote", "Against the deployed database rather than the local one").option("--env <name>", "Wrangler environment").example("flare user:add ada@example.com --role admin").action(async (email, options2) => {
-    process.exitCode = await addUser(email, options2);
-  });
+  cli.command("user:add <email>", "Create an account from the command line (the way in when signup is closed)").option("--role <role>", "Role to give them, e.g. admin").option("--password <password>", "Their password (generated and printed when omitted)").option("--name <name>", "Display name (default: the part before the @)").option("--remote", "Against the deployed database rather than the local one").option("--env <name>", "Wrangler environment").option("--skip-existing", "Succeed quietly if the account is already there (for seeds)").example("flare user:add ada@example.com --role admin").action(
+    async (email, options2) => {
+      process.exitCode = await addUser(email, options2);
+    }
+  );
   cli.command("doctor", "Check the things that are usually wrong: versions, env, bindings, migrations, drift, policies").option("--offline", "Skip the checks that ask the database").example("flare doctor").action(async (options2) => {
     process.exitCode = await doctor(options2);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaredev/cli",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "The flare command-line tool: create, generate, migrate, and deploy Flare apps",
   "license": "MIT",
   "author": "Muke Johnbaptist",
@@ -41,7 +41,7 @@
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
-    "@flaredev/core": "0.12.0"
+    "@flaredev/core": "0.12.2"
   },
   "engines": {
     "node": ">=22"

package/templates/app/.dev.vars.example

@@ -19,9 +19,8 @@ MAIL_FROM=
 # CLOUDINARY_API_KEY=
 # CLOUDINARY_API_SECRET=
 
-# STORAGE_DRIVER=uploadthing   # needs: pnpm add uploadthing
-# UPLOADTHING_TOKEN=
-# UPLOADTHING_APP_ID=
+# STORAGE_DRIVER=uploadthing
+# UPLOADTHING_TOKEN=            # the app id is inside it; there is no second variable
 
 # Both serve files from their own CDN, so a read URL is public and does not expire.
 # Set this to keep every read signed and proxied by the app instead.

package/templates/app/_gitignore

@@ -1,4 +1,11 @@
 node_modules
+
+# Prisma's generated client (Next.js stack). Generated output, not source: it is
+# rewritten by `prisma generate` on every install (postinstall) and on every build, so
+# committing it means hundreds of generated files in your diffs and a stale client the
+# moment someone changes the schema without regenerating.
+lib/generated/
+
 .env*
 !.env.example
 .dev.vars*

package/templates/app/lib/storage/uploadthing.ts

@@ -22,10 +22,13 @@ export interface UploadThingOptions {
   /** From the UploadThing dashboard. Defaults to `UPLOADTHING_TOKEN`. */
   token?: string;
   /**
-   * The app id, which is the subdomain files are served from. Defaults to
-   * `UPLOADTHING_APP_ID`.
+   * The app id, which is the subdomain files are served from.
+   *
+   * Almost never passed: it is already inside the token, and {@link appIdFromToken}
+   * reads it from there. Pass it only to serve from a different subdomain than the
+   * token names.
    */
-  appId: string;
+  appId?: string;
   /**
    * Serve reads from UploadThing's CDN. Default true, which is the reason to use it.
    * See {@link StorageBucket.publicUrl}: those files are readable by anyone with the
@@ -50,6 +53,38 @@ export function customIdFor(key: string): string {
   return key.replace(/[^A-Za-z0-9.-]/g, (char) => `_${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
 }
 
+/**
+ * The app id carried inside an UploadThing token.
+ *
+ * A v7 token is base64 JSON — `{ apiKey, appId, regions }` — so the id of the app it
+ * belongs to is already in your hands the moment you have the token. Asking for
+ * `UPLOADTHING_APP_ID` as well was asking for a value that cannot disagree with the
+ * token without being wrong, and the failure it produced was a quiet one: uploads
+ * succeeded and every read 404'd from a subdomain belonging to another app.
+ *
+ * Only the `appId` is read here. The apiKey stays in the token, which is what the SDK
+ * itself is given.
+ */
+export function appIdFromToken(token: string): string {
+  let decoded: string;
+  try {
+    decoded = typeof atob === "function" ? atob(token) : Buffer.from(token, "base64").toString("utf8");
+  } catch {
+    throw new Error("UPLOADTHING_TOKEN is not valid base64. Copy it again from https://uploadthing.com/dashboard.");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    throw new Error("UPLOADTHING_TOKEN does not decode to JSON. Copy it again from https://uploadthing.com/dashboard.");
+  }
+  const appId = (parsed as { appId?: unknown } | null)?.appId;
+  if (typeof appId !== "string" || appId === "") {
+    throw new Error("UPLOADTHING_TOKEN has no appId in it. Copy it again from https://uploadthing.com/dashboard.");
+  }
+  return appId;
+}
+
 /**
  * The part of UTApi this driver uses.
  *
@@ -82,7 +117,10 @@ async function api(token: string | undefined): Promise<UTApiLike> {
 
 export function uploadThingBucket(options: UploadThingOptions): StorageBucket {
   const publicDelivery = options.publicDelivery ?? true;
-  const deliveryUrl = (key: string) => `https://${options.appId}.ufs.sh/f/${customIdFor(key)}`;
+  // Read once rather than per request, so a malformed token is an error at startup
+  // instead of a 404 on somebody's first upload.
+  const appId = options.appId ?? appIdFromToken(options.token ?? process.env.UPLOADTHING_TOKEN ?? "");
+  const deliveryUrl = (key: string) => `https://${appId}.ufs.sh/f/${customIdFor(key)}`;
 
   return {
     async get(key: string): Promise<StorageObjectBody | null> {

package/templates/app/lib/storage.ts

@@ -74,8 +74,8 @@ function selectBucket(): StorageBucket {
       });
     case "uploadthing":
       return uploadThingBucket({
+        // The app id lives inside the token; the driver reads it from there.
         token: required("UPLOADTHING_TOKEN"),
-        appId: required("UPLOADTHING_APP_ID"),
         publicDelivery,
       });
     case "r2":