@flaredev/cli 0.4.1 → 0.5.1

package/templates/next/lib/audit.ts

@@ -0,0 +1,80 @@
+import { headers } from "next/headers";
+import { prisma } from "@/lib/db";
+import { dashboardSession } from "./dashboard";
+
+export type AuditAction = "create" | "update" | "delete" | "import" | "bulk-delete";
+
+export interface AuditEntry {
+  action: AuditAction;
+  resource: string;
+  recordId?: string | null;
+  recordLabel?: string | null;
+  changes?: Record<string, unknown> | null;
+}
+
+/**
+ * Record a change in the audit log.
+ *
+ * Never throws: an audit trail that can take the write down with it is worse than one
+ * with a gap, and the caller has already changed the database by the time we're here.
+ */
+export async function recordAudit(entry: AuditEntry): Promise<void> {
+  try {
+    const { session } = await dashboardSession();
+    const headerList = await headers();
+    await prisma.auditLog.create({
+      data: {
+        action: entry.action,
+        resource: entry.resource,
+        recordId: entry.recordId ?? null,
+        recordLabel: entry.recordLabel ?? null,
+        userId: session?.user.id ?? null,
+        userEmail: session?.user.email ?? null,
+        changes: (entry.changes ?? null) as never,
+        // Vercel puts the caller's address here; Cloudflare uses cf-connecting-ip.
+        ip: headerList.get("x-forwarded-for")?.split(",")[0]?.trim() ?? null,
+      },
+    });
+  } catch {
+    // Deliberately quiet.
+  }
+}
+
+/** Which fields moved, and from what to what. Only the differences, never the whole record. */
+export function diffFields(before: Record<string, unknown> | null | undefined, after: Record<string, unknown>): Record<string, { from: unknown; to: unknown }> {
+  const changes: Record<string, { from: unknown; to: unknown }> = {};
+  for (const [key, value] of Object.entries(after)) {
+    if (key === "updatedAt" || key === "createdAt") continue;
+    const previous = before?.[key];
+    const same = JSON.stringify(previous ?? null) === JSON.stringify(value ?? null);
+    if (!same) changes[key] = { from: previous ?? null, to: value ?? null };
+  }
+  return changes;
+}
+
+export interface AuditRow {
+  id: string;
+  action: string;
+  resource: string;
+  recordId: string | null;
+  recordLabel: string | null;
+  userEmail: string | null;
+  changes: Record<string, unknown> | null;
+  createdAt: Date;
+}
+
+/** The most recent entries, newest first. */
+export async function recentAudit(limit = 25, resource?: string): Promise<AuditRow[]> {
+  const rows = await prisma.auditLog.findMany({
+    where: resource ? { resource } : undefined,
+    orderBy: { createdAt: "desc" },
+    take: limit,
+  });
+  return rows as unknown as AuditRow[];
+}
+
+/** How many changes were recorded in the last `days` days, for the observability summary. */
+export async function auditCount(days = 7): Promise<number> {
+  const since = new Date(Date.now() - days * 86_400_000);
+  return prisma.auditLog.count({ where: { createdAt: { gte: since } } });
+}

package/templates/next/lib/auth-emails.ts

@@ -0,0 +1,92 @@
+import { prisma } from "@/lib/db";
+import { sendTransactionalEmail } from "./mail";
+
+/**
+ * Every email the sign-in flows send. Change the wording here; the layout comes from
+ * lib/mail.ts. Without RESEND_API_KEY these print to the console, links and codes included.
+ */
+
+const ignore = "If you didn't ask for this, you can ignore this email.";
+
+/** Accounts with two-factor sign-in never get a one-step email sign-in (it would skip the second factor). */
+async function usesTwoFactor(email: string): Promise<boolean> {
+  const row = await prisma.user.findUnique({ where: { email: email.toLowerCase() }, select: { twoFactorEnabled: true } });
+  return Boolean(row?.twoFactorEnabled);
+}
+
+async function sendTwoFactorNotice(email: string) {
+  await sendTransactionalEmail({
+    to: email,
+    subject: "Sign in with your password or a passkey",
+    heading: "Email sign-in is off for your account",
+    paragraphs: [
+      "Someone asked to sign in to your account by email. Your account uses two-factor authentication, so we don't send sign-in links or codes.",
+      "Sign in with your password and second factor, or with a passkey.",
+    ],
+    footer: ignore,
+  });
+}
+
+export async function sendMagicLink({ email, url }: { email: string; url: string }) {
+  if (await usesTwoFactor(email)) return sendTwoFactorNotice(email);
+  await sendTransactionalEmail({
+    to: email,
+    subject: "Your sign-in link",
+    heading: "Sign in",
+    paragraphs: ["Use this link to sign in. It works once and expires in 5 minutes."],
+    action: { label: "Sign in", url },
+    footer: ignore,
+    preheader: "Your sign-in link",
+  });
+}
+
+export async function sendEmailCode({ email, otp, type }: { email: string; otp: string; type: "sign-in" | "email-verification" | "forget-password" | "change-email" }) {
+  if (type === "sign-in" && (await usesTwoFactor(email))) return sendTwoFactorNotice(email);
+  const purpose = {
+    "sign-in": ["Your sign-in code", "Enter this code to sign in."],
+    "email-verification": ["Verify your email", "Enter this code to verify your email address."],
+    "forget-password": ["Reset your password", "Enter this code to choose a new password."],
+    "change-email": ["Confirm your new email", "Enter this code to confirm your new email address."],
+  }[type];
+  await sendTransactionalEmail({
+    to: email,
+    subject: `${purpose[0]}: ${otp}`,
+    heading: otp,
+    paragraphs: [purpose[1], "It expires in 5 minutes."],
+    footer: ignore,
+    preheader: purpose[0],
+  });
+}
+
+export async function sendTwoFactorCode({ user, otp }: { user: { email: string }; otp: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: `Your verification code: ${otp}`,
+    heading: otp,
+    paragraphs: ["Enter this code to finish signing in. It expires in 5 minutes."],
+    footer: "If you didn't just sign in, change your password: someone else knows it.",
+    preheader: "Your verification code",
+  });
+}
+
+export async function sendPasswordReset({ user, url }: { user: { email: string }; url: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: "Reset your password",
+    heading: "Reset your password",
+    paragraphs: ["Use this link to choose a new password. It expires in 1 hour."],
+    action: { label: "Choose a new password", url },
+    footer: ignore,
+  });
+}
+
+export async function sendVerificationEmail({ user, url }: { user: { email: string }; url: string }) {
+  await sendTransactionalEmail({
+    to: user.email,
+    subject: "Verify your email",
+    heading: "Verify your email",
+    paragraphs: ["Confirm this is your email address."],
+    action: { label: "Verify email", url },
+    footer: ignore,
+  });
+}

package/templates/next/lib/auth.ts

@@ -0,0 +1,156 @@
+import { after } from "next/server";
+import { passkey } from "@better-auth/passkey";
+import { prismaAdapter } from "@better-auth/prisma-adapter";
+import { betterAuth } from "better-auth";
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import { nextCookies } from "better-auth/next-js";
+import { admin } from "better-auth/plugins/admin";
+import { emailOTP } from "better-auth/plugins/email-otp";
+import { magicLink } from "better-auth/plugins/magic-link";
+import { twoFactor } from "better-auth/plugins/two-factor";
+import { hashPassword, verifyPassword } from "@flaredev/core";
+import { prisma } from "@/lib/db";
+import { authConfig, type SocialProvider } from "./auth-config";
+import { checkPassword, isBreachedPassword, PASSWORD_MAX_LENGTH } from "./password-rules";
+import { sendEmailCode, sendMagicLink, sendPasswordReset, sendTwoFactorCode, sendVerificationEmail } from "./auth-emails";
+
+const vars = process.env as Record<string, string | undefined>;
+
+/** Optional: set when serving from a custom domain (e.g. https://example.com). */
+const configuredURL = vars.BETTER_AUTH_URL;
+
+/** A provider's credentials from the environment, when both are set. */
+function credentials(prefix: string) {
+  const clientId = vars[`${prefix}_CLIENT_ID`];
+  const clientSecret = vars[`${prefix}_CLIENT_SECRET`];
+  return clientId && clientSecret ? { clientId, clientSecret } : undefined;
+}
+
+const providerSettings: Record<SocialProvider, Record<string, string> | undefined> = {
+  google: credentials("GOOGLE"),
+  github: credentials("GITHUB"),
+  // Apple's client secret is a JWT you generate from your key (see the auth guide).
+  apple: credentials("APPLE") && { ...credentials("APPLE")!, ...(vars.APPLE_APP_BUNDLE_ID ? { appBundleIdentifier: vars.APPLE_APP_BUNDLE_ID } : {}) },
+  // "common" accepts personal and work accounts; set a tenant id to allow only your organisation.
+  microsoft: credentials("MICROSOFT") && { ...credentials("MICROSOFT")!, tenantId: vars.MICROSOFT_TENANT_ID || "common" },
+};
+
+/** Social providers switched on in lib/auth-config.ts that also have credentials. */
+const socialProviders = Object.fromEntries(
+  authConfig.social.flatMap((provider) => (providerSettings[provider] ? [[provider, providerSettings[provider]]] : [])),
+);
+
+/** Endpoints of methods switched off in lib/auth-config.ts: refused, not just hidden. */
+function disabledPath(path: string): boolean {
+  if (!authConfig.magicLink && (path === "/sign-in/magic-link" || path === "/magic-link/verify")) return true;
+  if (!authConfig.emailOtp && (path.startsWith("/email-otp/") || path === "/sign-in/email-otp" || path === "/forget-password/email-otp")) return true;
+  if (!authConfig.passkeys && path.startsWith("/passkey/")) return true;
+  const { authenticator, email } = authConfig.twoFactor;
+  if (!authenticator && !email && path.startsWith("/two-factor/")) return true;
+  if (!authenticator && (path === "/two-factor/get-totp-uri" || path === "/two-factor/verify-totp")) return true;
+  if (!email && (path === "/two-factor/send-otp" || path === "/two-factor/verify-otp")) return true;
+  return false;
+}
+
+/** Where a new password arrives, and what it's called in the body. */
+const NEW_PASSWORD_FIELDS: Record<string, string> = {
+  "/sign-up/email": "password",
+  "/reset-password": "newPassword",
+  "/change-password": "newPassword",
+};
+
+/**
+ * The same password rules the sign-up and reset forms show as you type
+ * (lib/password-rules.ts), enforced here so the API agrees with the screens.
+ * Checked on the way in, before the password is hashed or stored.
+ */
+async function guardPassword(path: string, body: Record<string, unknown> | undefined) {
+  const field = NEW_PASSWORD_FIELDS[path];
+  if (!field) return;
+  const password = body?.[field];
+  if (typeof password !== "string") return;
+
+  if (password.length > PASSWORD_MAX_LENGTH) {
+    throw new APIError("BAD_REQUEST", { message: `Passwords can be at most ${PASSWORD_MAX_LENGTH} characters.` });
+  }
+  const check = checkPassword(password, [body?.email as string | undefined, body?.name as string | undefined]);
+  if (!check.valid) throw new APIError("BAD_REQUEST", { message: check.advice ?? "That password is too short." });
+
+  // A password in a public breach list is already guessed, however strong it looks.
+  if (authConfig.checkBreachedPasswords && (await isBreachedPassword(password))) {
+    throw new APIError("BAD_REQUEST", {
+      message: "That password has appeared in a data breach, so it isn't safe to use here. Pick a different one.",
+    });
+  }
+}
+
+export const auth = betterAuth({
+  appName: "__APP_NAME__",
+  secret: process.env.BETTER_AUTH_SECRET,
+  // Without BETTER_AUTH_URL, accept local dev on any port, a `flare dev --tunnel` URL and
+  // this app's workers.dev host. Cloudflare only routes hosts this Worker serves, so a
+  // deployed app never sees a trycloudflare.com host and the allowlist can't be spoofed.
+  baseURL: configuredURL || {
+    allowedHosts: ["localhost:*", "127.0.0.1:*", "*.trycloudflare.com", "__APP_NAME__.*.workers.dev"],
+  },
+  // Sign in with Apple posts back from Apple's own origin.
+  trustedOrigins: authConfig.social.includes("apple") ? ["https://appleid.apple.com"] : [],
+  database: prismaAdapter(prisma, { provider: "postgresql" }),
+  socialProviders,
+  account: {
+    // Signing in with Google as ada@example.com joins Ada's existing account (the provider has verified the address).
+    accountLinking: { enabled: true, trustedProviders: ["google", "github", "apple", "microsoft"] },
+  },
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: authConfig.requireEmailVerification,
+    // PBKDF2 via WebCrypto: the default scrypt exceeds Workers CPU limits.
+    password: { hash: hashPassword, verify: verifyPassword },
+    sendResetPassword: ({ user, url }) => sendPasswordReset({ user, url }),
+    resetPasswordTokenExpiresIn: 60 * 60,
+    // A password reset signs every other device out.
+    revokeSessionsOnPasswordReset: true,
+  },
+  emailVerification: {
+    sendVerificationEmail: ({ user, url }) => sendVerificationEmail({ user, url }),
+    sendOnSignUp: true,
+    autoSignInAfterVerification: true,
+  },
+  advanced: {
+    // Let emails and other deferred work finish after the response is sent.
+    // Next's equivalent of waitUntil: work that outlives the response, so sending a
+    // verification email doesn't hold the sign-up request open.
+    backgroundTasks: { handler: (promise: Promise<unknown>) => after(() => promise) },
+  },
+  hooks: {
+    before: createAuthMiddleware(async (ctx) => {
+      if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
+      await guardPassword(ctx.path, ctx.body as Record<string, unknown> | undefined);
+    }),
+  },
+  plugins: [
+    // Adds user.role (default "user") and admin APIs. The /admin area allows ADMIN_ROLES (lib/admin.ts).
+    admin({ defaultRole: "user", adminRoles: ["admin"] }),
+    magicLink({ sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }), expiresIn: 5 * 60, disableSignUp: false }),
+    emailOTP({ sendVerificationOTP: (data) => sendEmailCode(data), otpLength: 6, expiresIn: 5 * 60, allowedAttempts: 5 }),
+    twoFactor({
+      issuer: "__APP_NAME__",
+      otpOptions: { sendOTP: ({ user, otp }) => sendTwoFactorCode({ user, otp }), allowedAttempts: 5 },
+      // With only email codes switched on there's no authenticator app to confirm first.
+      skipVerificationOnEnable: !authConfig.twoFactor.authenticator,
+      // People who signed up with a social account have no password to confirm with;
+      // accounts that do have one must still give it.
+      allowPasswordless: true,
+    }),
+    passkey({ rpName: "__APP_NAME__" }),
+    // Must stay last: lets server actions set auth cookies.
+    nextCookies(),
+  ],
+});
+
+export type Session = typeof auth.$Infer.Session;
+
+/** OAuth providers switched on and configured, e.g. ["github"], for the sign-in buttons. */
+export function enabledSocialProviders(): SocialProvider[] {
+  return Object.keys(socialProviders) as SocialProvider[];
+}

package/templates/next/lib/dashboard.ts

@@ -0,0 +1,161 @@
+import { headers } from "next/headers";
+import { notFound, redirect } from "next/navigation";
+import { allowedActions, can, columnName, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
+import { createResourceStore, prismaRows, type PrismaDelegate, type ResourceStore } from "@flaredev/core/server";
+import { prisma } from "@/lib/db";
+import { policies } from "@/policies";
+import { resourceTables } from "@/resources/server";
+import { currentUser } from "./api";
+import { auth } from "./auth";
+import { cached, resourceTag, revalidateResource, TTL } from "./cache";
+
+/**
+ * The dashboard's view of a resource, on the Next.js stack.
+ *
+ * The same shape as the Cloudflare one — same exports, same behaviour — over Prisma and
+ * Postgres instead of Drizzle and D1. The store itself is shared: only where its rows
+ * come from differs.
+ */
+
+export const ADMIN_ROLES = ["admin", "staff"];
+
+export function policyFor(resourceName: string): Policy | undefined {
+  return (policies as Record<string, Policy | undefined>)[resourceName];
+}
+
+export async function dashboardSession() {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) return { session: null, role: null, allowed: false } as const;
+  const role = (session.user as { role?: string | null }).role ?? null;
+  const readable = allResources().some((resource) => can(policyFor(resource.name), role, "read"));
+  return { session, role, allowed: (role !== null && ADMIN_ROLES.includes(role)) || readable } as const;
+}
+
+/** For admin pages: redirects signed-out visitors to sign-in and users without access to the home page. */
+export async function requireDashboard(returnTo = "/dashboard") {
+  const { session, role, allowed } = await dashboardSession();
+  if (!session) redirect(`/sign-in?next=${encodeURIComponent(returnTo)}`);
+  if (!allowed) redirect("/?error=forbidden");
+  return { session, role };
+}
+
+/**
+ * For resource pages: also requires the policy to allow `action` on this resource.
+ * Sends the user somewhere they can actually go — the list when they may read it,
+ * the dashboard when they may not.
+ */
+export async function requireAccess(resource: Resource, action: PolicyAction) {
+  const { session, role } = await requireDashboard(resourcePath(resource));
+  const policy = policyFor(resource.name);
+  if (!can(policy, role, action)) {
+    redirect(action !== "read" && can(policy, role, "read") ? resourcePath(resource) : "/dashboard?error=forbidden");
+  }
+  return { session, role };
+}
+
+/** What the current user may do with a resource, for hiding actions they can't use. */
+export async function adminPermissions(resourceName: string) {
+  const { role } = await dashboardSession();
+  return allowedActions(policyFor(resourceName), role);
+}
+
+const stores = new Map<string, ResourceStore>();
+
+/** CRUD store for a resource by name (404 for unknown names). */
+export function dashboardStore(name: string): ResourceStore {
+  const entry = (resourceTables as unknown as Record<string, { resource: Resource; delegate: PrismaDelegate } | undefined>)[name];
+  if (!entry) notFound();
+  let store = stores.get(name);
+  if (!store) {
+    store = createResourceStore({
+      resource: entry.resource,
+      rows: prismaRows(entry.delegate, prisma),
+      onChange: revalidateResource,
+      currentUser,
+    });
+    stores.set(name, store);
+  }
+  return store;
+}
+
+/**
+ * Every number the stats above a resource's table need, in one query.
+ *
+ * The total, how many arrived in the last week and the week before, and how many hold
+ * each value of a status field — one grouped scan, summed up here. Written as SQL
+ * because Prisma's aggregation API can't express "count these rows, and also count the
+ * subset of them created since Tuesday" in a single round trip.
+ *
+ * The table and column names come from the descriptor, never from a request, and are
+ * quoted; nothing a visitor types reaches this.
+ */
+export interface ResourceStats {
+  total: number;
+  /** Created in the last `days` days, and in the `days` before that. */
+  current: number;
+  previous: number;
+  /** Rows per value of the grouped field, when one was asked for. */
+  values: Record<string, number>;
+}
+
+export function resourceStats(name: string, field?: string, days = 7): Promise<ResourceStats> {
+  const read = cached(
+    async (resourceName: string, key: string | undefined, windowDays: number): Promise<ResourceStats> => {
+      const entry = (resourceTables as unknown as Record<string, { resource: Resource } | undefined>)[resourceName];
+      if (!entry) return { total: 0, current: 0, previous: 0, values: {} };
+
+      const table = `"${entry.resource.table}"`;
+      const grouped = key && entry.resource.fields[key] ? `"${columnName(key)}"` : undefined;
+      const window = windowDays * 86_400_000;
+      const since = new Date(Date.now() - window).toISOString();
+      const before = new Date(Date.now() - window * 2).toISOString();
+
+      const select = [
+        "count(*)::int as total",
+        `count(*) filter (where "created_at" >= '${since}')::int as current`,
+        `count(*) filter (where "created_at" >= '${before}' and "created_at" < '${since}')::int as previous`,
+        ...(grouped ? [`${grouped} as value`] : []),
+      ].join(", ");
+      const query = `select ${select} from ${table}${grouped ? ` group by ${grouped}` : ""}`;
+
+      const rows = (await prisma.$queryRawUnsafe(query)) as { total: number; current: number; previous: number; value?: unknown }[];
+      const stats: ResourceStats = { total: 0, current: 0, previous: 0, values: {} };
+      for (const row of rows) {
+        stats.total += Number(row.total ?? 0);
+        stats.current += Number(row.current ?? 0);
+        stats.previous += Number(row.previous ?? 0);
+        if (grouped) stats.values[String(row.value ?? "")] = Number(row.total ?? 0);
+      }
+      return stats;
+    },
+    ["flare", "resource-stats"],
+    { tags: [resourceTag(name)], revalidate: TTL.medium },
+  );
+  return read(name, field, days);
+}
+
+/** How many records a resource has. One field of {@link resourceStats}. */
+export async function recordCount(name: string): Promise<number> {
+  return (await resourceStats(name)).total;
+}
+
+/** Percentage change between two periods, or undefined when there's nothing to compare. */
+export function trend(current: number, previous: number): number | undefined {
+  if (previous === 0) return current === 0 ? undefined : 100;
+  return ((current - previous) / previous) * 100;
+}
+
+/** Every resource descriptor (unfiltered): navigation uses `visibleResources()` instead. */
+export function allResources(): Resource[] {
+  return Object.values(resourceTables as unknown as Record<string, { resource: Resource }>).map((entry) => entry.resource);
+}
+
+/** Resources the current user may read, for the sidebar and dashboard. */
+export async function visibleResources(): Promise<Resource[]> {
+  const { role } = await dashboardSession();
+  return allResources().filter((resource) => can(policyFor(resource.name), role, "read"));
+}
+
+export function resourcePath(resource: Resource, ...parts: string[]) {
+  return ["/dashboard", resource.slug, ...parts].join("/");
+}

package/templates/next/lib/db.ts

@@ -0,0 +1,24 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "@/lib/generated/prisma/client";
+
+/**
+ * The Prisma client, one per process.
+ *
+ * Prisma 7 needs a driver adapter rather than a connection string in the schema. This
+ * one is the ordinary Postgres driver, which talks to anything that speaks Postgres:
+ * Neon's pooled endpoint, Supabase, RDS, or the container you run while developing.
+ * Next runs on Node, so there is nothing to gain from a serverless HTTP driver and a
+ * great deal to lose — `@prisma/adapter-neon` can't reach a database on localhost.
+ *
+ * Next reloads modules on every edit in development, and a fresh client each time would
+ * exhaust the connection limit within a few saves; hence the global.
+ */
+const makeClient = () => new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) });
+
+const globalForPrisma = globalThis as unknown as { prisma?: ReturnType<typeof makeClient> };
+
+export const prisma = globalForPrisma.prisma ?? makeClient();
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;
+
+/** Named to match the Cloudflare stack, so code that takes a database reads the same. */
+export const getDb = () => prisma;

package/templates/next/lib/mail.ts

@@ -0,0 +1,35 @@
+import { createMailer, renderTransactionalEmail, type TransactionalEmail } from "@flaredev/core";
+
+/**
+ * Transactional email via Resend.
+ *
+ * Without RESEND_API_KEY (e.g. local dev) emails are printed to the console
+ * instead of sent. MAIL_FROM must use a domain verified in Resend. The fallback
+ * sandbox sender only delivers to your own Resend account address.
+ */
+export const mailer = createMailer({
+  apiKey: process.env.RESEND_API_KEY,
+  from: process.env.MAIL_FROM || "__APP_NAME__ <onboarding@resend.dev>",
+});
+
+/**
+ * Render and send a transactional email. Resolves to `{ data, error }` and never throws for API errors.
+ *
+ *   const { error } = await sendTransactionalEmail({
+ *     to: user.email,
+ *     subject: "Your order has shipped",
+ *     heading: "On its way",
+ *     paragraphs: [`Order #${order.id} left our warehouse today.`],
+ *     action: { label: "Track order", url: `https://example.com/orders/${order.id}` },
+ *     idempotencyKey: `order-shipped/${order.id}`,
+ *   });
+ */
+export async function sendTransactionalEmail({
+  to,
+  subject,
+  idempotencyKey,
+  ...content
+}: Omit<TransactionalEmail, "appName"> & { to: string | string[]; subject: string; idempotencyKey?: string }) {
+  const { html, text } = renderTransactionalEmail({ appName: "__APP_NAME__", ...content });
+  return mailer.send({ to, subject, html, text, idempotencyKey });
+}

package/templates/next/lib/realtime.ts

@@ -0,0 +1,23 @@
+/**
+ * Realtime, on the Next.js stack.
+ *
+ * The Cloudflare stack gives every channel a Durable Object: one address, one thread,
+ * its own storage, and websockets that stay open. Vercel has no equivalent — functions
+ * don't hold connections — so rather than pretend, this says so, and publishing is a
+ * no-op that never breaks a write.
+ *
+ * If you need it here, the shape to reach for is a hosted pub/sub (Ably, Pusher,
+ * Upstash) behind these same two functions.
+ */
+import type { RealtimeAuthorize } from "@flaredev/core/realtime/server";
+
+export const authorizeRealtime: RealtimeAuthorize = () => false;
+
+export interface RealtimeChannel {
+  publish(event: string, data: unknown): Promise<void>;
+}
+
+/** A channel that accepts publishes and drops them, so callers need no special case. */
+export function realtimeChannel(_name: string): RealtimeChannel {
+  return { publish: async () => undefined };
+}

package/templates/next/lib/redis.ts

@@ -0,0 +1,17 @@
+import { Redis } from "@upstash/redis";
+
+/**
+ * Upstash Redis, over HTTP.
+ *
+ * Next's own data cache (`cached()` in lib/cache.ts) handles query caching. This is for
+ * the things a cache can't do: rate limits, locks, anything that has to be true across
+ * every instance at once. It talks HTTP rather than a socket, so a serverless function
+ * needs no connection pool.
+ *
+ * Unset credentials give you `null` rather than a crash, so an app that doesn't use it
+ * doesn't have to configure it.
+ */
+export const redis =
+  process.env.UPSTASH_REDIS_REST_URL && process.env.UPSTASH_REDIS_REST_TOKEN
+    ? new Redis({ url: process.env.UPSTASH_REDIS_REST_URL, token: process.env.UPSTASH_REDIS_REST_TOKEN })
+    : null;

package/templates/next/lib/storage.ts

@@ -0,0 +1,57 @@
+import { AwsClient } from "aws4fetch";
+import { createObjectKey, createStorage } from "@flaredev/core";
+
+/**
+ * File storage on R2, over its S3-compatible API.
+ *
+ * R2 rather than Vercel Blob for one reason: R2 charges nothing to serve what it
+ * stores. On a file-heavy app that is the difference between a small bill and a large
+ * one, and it costs nothing to use from outside Cloudflare — see the cost guide.
+ *
+ * `aws4fetch` signs the requests; it is a few kilobytes and works in any runtime, unlike
+ * the AWS SDK. Everything above this — the upload widget, the signed-URL helpers, the
+ * file field — is the same code the Cloudflare stack runs.
+ */
+const client = new AwsClient({
+  accessKeyId: process.env.R2_ACCESS_KEY_ID ?? "",
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY ?? "",
+  service: "s3",
+  region: "auto",
+});
+
+const endpoint = `${process.env.R2_ENDPOINT ?? ""}/${process.env.R2_BUCKET ?? ""}`;
+
+/** The bucket, shaped the way @flaredev/core expects, over plain HTTP calls. */
+const bucket = {
+  async get(key: string) {
+    const response = await client.fetch(`${endpoint}/${encodeURIComponent(key)}`);
+    if (!response.ok || !response.body) return null;
+    return {
+      body: response.body,
+      httpMetadata: { contentType: response.headers.get("content-type") ?? undefined },
+      size: Number(response.headers.get("content-length") ?? 0),
+      // R2 returns the object's ETag quoted, which is what the header wants back.
+      httpEtag: response.headers.get("etag") ?? "",
+    };
+  },
+  async put(key: string, value: ReadableStream | ArrayBuffer | string | null, options?: { httpMetadata?: { contentType?: string } }) {
+    await client.fetch(`${endpoint}/${encodeURIComponent(key)}`, {
+      method: "PUT",
+      body: value,
+      headers: options?.httpMetadata?.contentType ? { "content-type": options.httpMetadata.contentType } : undefined,
+    });
+  },
+  async delete(keys: string | string[]) {
+    for (const key of [keys].flat()) {
+      await client.fetch(`${endpoint}/${encodeURIComponent(key)}`, { method: "DELETE" });
+    }
+  },
+};
+
+export const storage = createStorage({
+  bucket,
+  // Signing keys are derived from the auth secret with a storage-specific label.
+  secret: process.env.BETTER_AUTH_SECRET ?? "",
+});
+
+export { createObjectKey };