create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/lib/storage.ts

@@ -0,0 +1,311 @@
+import 'server-only'
+
+import {
+  DeleteObjectCommand,
+  PutObjectCommand,
+  S3Client
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { createId } from '@paralleldrive/cuid2'
+import { and, eq, lt } from 'drizzle-orm'
+import { db } from '~/db'
+import { fileUploadsTable } from '~/db/schema'
+import { env } from '~/env'
+import {
+  PRESIGNED_URL_TTL_SECONDS,
+  R2_UPLOAD_EXTENSION_BY_MIME_TYPE,
+  TEMP_CLEANUP_THRESHOLD_MS,
+  type R2UploadMimeType
+} from './constants'
+import { AppError, AppErrorCode } from './errors'
+import {
+  canPersistImageValue,
+  isDataImageUrl,
+  isR2ObjectKey
+} from './image-url'
+
+/*
+The R2 bucket needs this CORS policy for browser uploads:
+[
+  {
+    "AllowedOrigins": ["http://localhost:3000"],
+    "AllowedMethods": ["PUT"],
+    "AllowedHeaders": ["content-type", "content-length"]
+  }
+]
+*/
+
+/** True when all five R2 env vars are set. When false, uploads fall back to base64 data URLs. */
+export function isR2Configured(): boolean {
+  return !!(
+    env.R2_ACCOUNT_ID &&
+    env.R2_ACCESS_KEY_ID &&
+    env.R2_SECRET_ACCESS_KEY &&
+    env.R2_BUCKET_NAME &&
+    env.R2_PUBLIC_URL
+  )
+}
+
+let _r2Client: S3Client | null = null
+
+/**
+ * `requestChecksumCalculation: 'WHEN_REQUIRED'` avoids signing
+ * `x-amz-checksum-crc32=AAAAAA==` (empty body) into presigned PUTs, which
+ * breaks non-empty uploads on backends that validate the header.
+ */
+function getR2Client(): S3Client {
+  if (_r2Client) return _r2Client
+
+  if (!isR2Configured()) {
+    // A configuration bug, not a customer error: masked and recorded.
+    throw new Error('R2 storage is not configured.')
+  }
+
+  _r2Client = new S3Client({
+    region: 'auto',
+    endpoint: `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    credentials: {
+      accessKeyId: env.R2_ACCESS_KEY_ID!,
+      secretAccessKey: env.R2_SECRET_ACCESS_KEY!
+    },
+    requestChecksumCalculation: 'WHEN_REQUIRED',
+    responseChecksumValidation: 'WHEN_REQUIRED'
+  })
+
+  return _r2Client
+}
+
+/**
+ * Throws unless `key` sits under `uploads/organizations/<organizationId>/` and
+ * has a `file_uploads` row recorded for that same organization.
+ *
+ * Call this on any R2 key that comes from user input before it is persisted,
+ * confirmed, or deleted, so a request can never reference another tenant's
+ * object.
+ */
+export async function assertOwnedR2Key(
+  key: string,
+  organizationId: string
+): Promise<void> {
+  if (!key.startsWith(`uploads/organizations/${organizationId}/`)) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to use this file.'
+    )
+  }
+
+  const exists = await db.query.fileUploadsTable.findFirst({
+    where: and(
+      eq(fileUploadsTable.key, key),
+      eq(fileUploadsTable.organizationId, organizationId)
+    ),
+    columns: { id: true }
+  })
+
+  if (!exists) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to use this file.'
+    )
+  }
+}
+
+/**
+ * Deletes a file from R2 and removes its tracking row.
+ *
+ * Trusted-caller primitive with no ownership check. Validate a key that came
+ * from user input with {@link assertOwnedR2Key} first.
+ */
+export async function deleteFile(key: string): Promise<void> {
+  await getR2Client().send(
+    new DeleteObjectCommand({ Bucket: env.R2_BUCKET_NAME, Key: key })
+  )
+
+  await db.delete(fileUploadsTable).where(eq(fileUploadsTable.key, key))
+}
+
+/**
+ * Presigns a PUT for a direct browser-to-R2 upload and records it as
+ * temporary. Content-Type is signed, so the browser cannot upload `text/html`
+ * under an image key.
+ *
+ * The browser PUTs the file to `uploadUrl`, then the action that saves the
+ * resource calls {@link confirmUpload} with the returned `key`.
+ */
+export async function generateUploadUrl(params: {
+  filename: string
+  mimeType: R2UploadMimeType
+  size: number
+  uploadedBy: string
+  organizationId: string
+}): Promise<{ uploadUrl: string; key: string }> {
+  const ext = R2_UPLOAD_EXTENSION_BY_MIME_TYPE[params.mimeType]
+  const fileId = createId()
+  const key = `uploads/organizations/${params.organizationId}/${fileId}.${ext}`
+
+  const uploadUrl = await getSignedUrl(
+    getR2Client(),
+    new PutObjectCommand({
+      Bucket: env.R2_BUCKET_NAME!,
+      Key: key,
+      ContentType: params.mimeType,
+      ContentLength: params.size
+    }),
+    {
+      expiresIn: PRESIGNED_URL_TTL_SECONDS,
+      signableHeaders: new Set(['content-type'])
+    }
+  )
+
+  await db.insert(fileUploadsTable).values({
+    id: `file_upload_${fileId}`,
+    key,
+    originalName: params.filename,
+    mimeType: params.mimeType,
+    size: params.size,
+    isTemp: true,
+    uploadedBy: params.uploadedBy,
+    organizationId: params.organizationId
+  })
+
+  return { uploadUrl, key }
+}
+
+/**
+ * Marks an upload permanent and deletes the file it replaces.
+ *
+ * Call it in the action that saves the resource. `newKey` must belong to
+ * `organizationId`, and this throws otherwise. Deleting `oldKey` is
+ * best-effort and never blocks the save.
+ */
+export async function confirmUpload(
+  newKey: string,
+  organizationId: string,
+  oldKey?: string | null
+): Promise<void> {
+  await assertOwnedR2Key(newKey, organizationId)
+
+  await db
+    .update(fileUploadsTable)
+    .set({ isTemp: false })
+    .where(eq(fileUploadsTable.key, newKey))
+
+  if (oldKey && oldKey !== newKey)
+    await deleteOwnedFileQuietly(oldKey, organizationId)
+}
+
+/**
+ * Deletes a replaced or cleared file when `organizationId` owns it. Failures
+ * are swallowed: a stale object costs storage, not correctness.
+ */
+export async function deleteOwnedFileQuietly(
+  key: string,
+  organizationId: string
+): Promise<void> {
+  if (!isR2Key(key) || !isR2Configured()) return
+
+  const owned = await assertOwnedR2Key(key, organizationId)
+    .then(() => true)
+    .catch(() => false)
+
+  if (owned) await deleteFile(key).catch(() => {})
+}
+
+/**
+ * Deletes every upload an organization owns, from R2 and the database.
+ * `file_uploads.organization_id` restricts deletes, so the organization row
+ * can only go once this has run.
+ */
+export async function deleteOrganizationUploads(
+  organizationId: string
+): Promise<void> {
+  const uploads = await db
+    .select({ key: fileUploadsTable.key })
+    .from(fileUploadsTable)
+    .where(eq(fileUploadsTable.organizationId, organizationId))
+
+  if (isR2Configured()) {
+    for (const upload of uploads) {
+      await deleteFile(upload.key)
+    }
+  }
+
+  await db
+    .delete(fileUploadsTable)
+    .where(eq(fileUploadsTable.organizationId, organizationId))
+}
+
+/** True when `value` is an R2 object key (`uploads/organizations/<id>/<file>.<ext>`). */
+export function isR2Key(value: string | null | undefined): value is string {
+  return !!value && isR2ObjectKey(value)
+}
+
+/**
+ * Rejects image values that must not be written to a resource. This blocks
+ * `data:` URLs when R2 is configured. Ownership stays in {@link assertOwnedR2Key}.
+ */
+export function assertPersistableImageValue(
+  value: string | null | undefined
+): void {
+  if (!value) return
+  if (canPersistImageValue(value, isR2Configured())) return
+  throw new AppError(
+    AppErrorCode.BAD_REQUEST,
+    'Upload an image file. Embedded images are not stored.'
+  )
+}
+
+/**
+ * Resolves a stored image value to a renderable URL.
+ *
+ * - R2 object key: prefixed with `R2_PUBLIC_URL`
+ * - `data:image/*;base64,...` (dev without R2): returned as-is
+ * - anything else, including `https://` and `javascript:`: `null`
+ */
+export function resolveImageUrl(
+  value: string | null | undefined
+): string | null {
+  if (!value) return null
+  if (isR2ObjectKey(value)) {
+    if (!isR2Configured()) return null
+    return `${env.R2_PUBLIC_URL}/${value}`
+  }
+  if (isDataImageUrl(value)) return value
+  return null
+}
+
+/**
+ * Deletes temporary uploads older than {@link TEMP_CLEANUP_THRESHOLD_MS}.
+ * Per-file errors are counted, not thrown, so one failure cannot abort the
+ * batch. `bun run storage:cleanup` runs it; schedule that command.
+ */
+export async function cleanupTempUploads(): Promise<{
+  deleted: number
+  errors: number
+}> {
+  const threshold = new Date(Date.now() - TEMP_CLEANUP_THRESHOLD_MS)
+
+  const stale = await db
+    .select({ key: fileUploadsTable.key })
+    .from(fileUploadsTable)
+    .where(
+      and(
+        eq(fileUploadsTable.isTemp, true),
+        lt(fileUploadsTable.createdAt, threshold)
+      )
+    )
+
+  let deleted = 0
+  let errors = 0
+
+  for (const file of stale) {
+    try {
+      await deleteFile(file.key)
+      deleted++
+    } catch {
+      errors++
+    }
+  }
+
+  return { deleted, errors }
+}

package/template/saas-starter/src/lib/stripe.ts

@@ -0,0 +1,9 @@
+import 'server-only'
+
+import Stripe from 'stripe'
+import { env } from '~/env'
+
+/** Pinned to the API version this `stripe` SDK release was built for. Bump both together. */
+export const stripeClient = new Stripe(env.STRIPE_SECRET_KEY, {
+  apiVersion: '2026-08-26.dahlia'
+})

package/template/saas-starter/src/lib/toast-message.ts

@@ -0,0 +1,101 @@
+'use client'
+
+import { toast } from 'sonner'
+
+const DEFAULT_ERROR = 'The request did not finish. Try again in a few minutes.'
+
+type ActionResultLike = {
+  serverError?: string
+  validationErrors?: unknown
+}
+
+/**
+ * Displays a success toast notification to the user.
+ */
+export const toastSuccessMessage = (message: string) =>
+  toast.success(message, {
+    richColors: true,
+    position: 'top-center'
+  })
+
+/**
+ * Displays an informational toast (neutral, non-error feedback).
+ */
+export const toastInfoMessage = (message: string) =>
+  toast.info(message, {
+    richColors: true,
+    position: 'top-center'
+  })
+
+/**
+ * Displays an error toast. Uses a default message when none is provided.
+ */
+export const toastErrorMessage = (message?: string) =>
+  toast.error(message || DEFAULT_ERROR, {
+    richColors: true,
+    position: 'top-center'
+  })
+
+/**
+ * Toast an action failure from `await someAction(...)`.
+ * Returns true when a toast was shown so callers can bail.
+ *
+ * @example
+ * const result = await upsertTableAction(values)
+ * if (toastIfActionFailed(result)) return
+ */
+export function toastIfActionFailed(
+  result: ActionResultLike | undefined | null
+): boolean {
+  if (!result) return false
+  if (result.serverError) {
+    toastErrorMessage(result.serverError)
+    return true
+  }
+  if (result.validationErrors) {
+    toastErrorMessage('Check the highlighted fields and try again.')
+    return true
+  }
+  return false
+}
+
+/**
+ * Toast a failure from hooks (`useSafeActionMutation`, `useAction`) or a thrown Error.
+ *
+ * Accepts:
+ * - `SafeActionError` / `Error` (`message`)
+ * - `useAction` error bag (`{ serverError, validationErrors }`)
+ * - plain string
+ *
+ * @example
+ * onError: error => toastActionError(error, 'Failed to save')
+ * onError: ({ error }) => toastActionError(error, 'Failed to save')
+ */
+export function toastActionError(
+  error: unknown,
+  fallback = DEFAULT_ERROR
+): void {
+  if (typeof error === 'string' && error.trim()) {
+    toastErrorMessage(error)
+    return
+  }
+
+  if (error && typeof error === 'object') {
+    const bag = error as ActionResultLike & { message?: string }
+
+    if (typeof bag.serverError === 'string' && bag.serverError) {
+      toastErrorMessage(bag.serverError)
+      return
+    }
+    if (bag.validationErrors) {
+      toastErrorMessage('Check the highlighted fields and try again.')
+      return
+    }
+    if (typeof bag.message === 'string' && bag.message.trim()) {
+      toastErrorMessage(bag.message)
+      return
+    }
+  }
+
+  toastErrorMessage(fallback)
+}

package/template/saas-starter/src/lib/validations.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared Zod fragments for action input and forms.
+ *
+ * Client-safe: no env, DB, or server-only imports, so forms can reuse the
+ * exact schema their action validates with.
+ */
+import z from 'zod'
+import {
+  MAX_COMMENT_LENGTH,
+  MAX_IMAGE_URL_LENGTH,
+  MAX_MESSAGE_LENGTH,
+  MAX_RATING,
+  MAX_SLUG_LENGTH,
+  MIN_RATING
+} from '~/lib/constants'
+import { isStoredImageValue } from '~/lib/image-url'
+
+/**
+ * Phone number: 7 to 15 digits once separators are removed (E.164 maximum).
+ * Allowed characters are digits, `+`, `-`, `()`, `.`, and spaces.
+ */
+export const phoneValidation = z
+  .string()
+  .trim()
+  .max(20)
+  .regex(/^[\d+\-().\s]+$/, 'Enter a valid phone number.')
+  .refine(value => {
+    const digits = value.replace(/\D/g, '').length
+    return digits >= 7 && digits <= 15
+  }, 'Enter a phone number with 7 to 15 digits.')
+
+/** Email address, trimmed and lowercased. */
+export const emailValidation = z.email().trim().toLowerCase()
+
+/** Required short string, 1 to 255 characters after trimming. */
+export const stringValidation = z.string().trim().min(1).max(255)
+
+/** Optional short string (max 255). Empty string is allowed after trim. */
+export const optionalStringValidation = z.string().trim().max(255).optional()
+
+/** Required body for support tickets and similar messages. */
+export const requiredMessageValidation = z
+  .string()
+  .trim()
+  .min(1, 'Enter a message.')
+  .max(MAX_MESSAGE_LENGTH)
+
+/** Required feedback comment. */
+export const requiredCommentValidation = z
+  .string()
+  .trim()
+  .min(1, 'Write your feedback.')
+  .max(MAX_COMMENT_LENGTH)
+
+/** Star rating from 1 to 5. */
+export const ratingValidation = z.number().int().min(MIN_RATING).max(MAX_RATING)
+
+/**
+ * R2 object key or `data:image/*;base64,...` URL. Empty after trim is allowed
+ * so a cleared field still parses; the action treats it as "no image".
+ */
+export const imageUrlValidation = z
+  .string()
+  .trim()
+  .max(MAX_IMAGE_URL_LENGTH)
+  .refine(value => value === '' || isStoredImageValue(value), {
+    message: 'Upload an image file. External URLs are not stored.'
+  })
+
+/**
+ * URL slug: lowercase letters, numbers, and single hyphens between segments.
+ * Rejects empty strings, path segments, and query characters.
+ */
+export const slugValidation = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .min(1, 'Enter a slug.')
+  .max(MAX_SLUG_LENGTH)
+  .regex(
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    'Use only lowercase letters, numbers, and hyphens.'
+  )
+
+/**
+ * Build a URL slug from a display name.
+ * Returns an empty string when nothing remains, such as an emoji-only name.
+ */
+export function slugifyName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .slice(0, MAX_SLUG_LENGTH)
+}

package/template/saas-starter/src/proxy.ts

@@ -0,0 +1,48 @@
+import { type NextRequest, NextResponse } from 'next/server'
+
+/**
+ * Proxy middleware function
+ *
+ * Forwards the request pathname (+ search) as `x-pathname` so server layouts
+ * can build a same-origin login callback without losing deep links.
+ * @returns NextResponse that continues the request chain
+ */
+export function proxy(request: NextRequest) {
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set(
+    'x-pathname',
+    `${request.nextUrl.pathname}${request.nextUrl.search}`
+  )
+
+  return NextResponse.next({
+    request: { headers: requestHeaders }
+  })
+}
+
+/**
+ * Middleware configuration
+ *
+ * Defines which routes this middleware should be applied to using the matcher pattern.
+ */
+export const config = {
+  matcher: [
+    {
+      /**
+       * Route matching pattern
+       *
+       * This regex pattern matches all routes EXCEPT:
+       * - /_next/static - Next.js static assets
+       * - /_next/image - Next.js image optimization
+       * - /favicon.ico - Browser favicon
+       * - /.well-known/workflow/ - Internal workflow paths
+       *
+       * Excluding these paths ensures that:
+       * 1. Static assets load efficiently without middleware overhead
+       * 2. Image optimization is not interrupted
+       * 3. Workflow execution and resumption function correctly
+       */
+      source:
+        '/((?!_next/static|_next/image|favicon.ico|.well-known/workflow/).*)'
+    }
+  ]
+}

package/template/saas-starter/src/scripts/cleanup-temp-uploads.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Deletes uploads that were never confirmed, such as a logo
+ * picked and then abandoned. Run it on a schedule (for example hourly) with
+ * `bun run storage:cleanup`.
+ */
+
+import { cleanupTempUploads, isR2Configured } from '~/lib/storage'
+
+if (import.meta.main) {
+  if (!isR2Configured()) {
+    console.info('R2 is not configured; there are no temporary uploads.')
+    process.exit(0)
+  }
+
+  cleanupTempUploads()
+    .then(({ deleted, errors }) => {
+      console.info(`Deleted ${deleted} temporary uploads; ${errors} failed.`)
+      process.exit(errors ? 1 : 0)
+    })
+    .catch(err => {
+      console.error('Error cleaning up temporary uploads:', err)
+      process.exit(1)
+    })
+}

package/template/saas-starter/src/scripts/reset-db.ts

@@ -0,0 +1,22 @@
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+import { env } from '~/env'
+
+const resetDb = async () => {
+  if (env.APP_ENV === 'production') {
+    throw new Error('Cannot reset database in production environment.')
+  }
+
+  await db.execute(sql`DROP SCHEMA IF EXISTS public CASCADE;`)
+  await db.execute(sql`CREATE SCHEMA public;`)
+}
+
+if (import.meta.main) {
+  try {
+    await resetDb()
+    process.exit(0)
+  } catch (err) {
+    console.error('Error running reset-db:', err)
+    process.exit(1)
+  }
+}

package/template/saas-starter/src/scripts/seed.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Seeds a local database with a superadmin, a regular user,
+ * and one organization on the free plan.
+ *
+ * Sign in with a magic link sent to either seeded address, so point them at
+ * inboxes you control. A successful run writes a `seed_runs` marker and later
+ * runs do nothing; reset the database to seed again. Everything runs in one
+ * transaction, so a failure leaves no partial data.
+ */
+
+import { db } from '~/db'
+import {
+  SEED_RUN_MARKER_ID,
+  membersTable,
+  organizationSubscriptionsTable,
+  organizationsTable,
+  seedRunsTable,
+  usersTable
+} from '~/db/schema'
+
+/** Seeds `database` once. Returns `skipped: true` when a seed already ran. */
+export async function seedDatabase(
+  database: typeof db = db
+): Promise<{ skipped: boolean }> {
+  const [existingSeedRun] = await database
+    .select({ id: seedRunsTable.id })
+    .from(seedRunsTable)
+    .limit(1)
+
+  if (existingSeedRun) return { skipped: true }
+
+  await database.transaction(async tx => {
+    const superadminId = usersTable.id.defaultFn!()
+    const userId = usersTable.id.defaultFn!()
+    const organizationId = organizationsTable.id.defaultFn!()
+
+    await tx.insert(usersTable).values([
+      {
+        id: superadminId,
+        name: 'Super Admin',
+        email: 'superadmin@example.com',
+        emailVerified: true,
+        role: 'superadmin'
+      },
+      {
+        id: userId,
+        name: 'Demo User',
+        email: 'user@example.com',
+        emailVerified: true,
+        role: 'user'
+      }
+    ])
+
+    await tx.insert(organizationsTable).values({
+      id: organizationId,
+      name: 'Demo Organization',
+      slug: 'demo-organization'
+    })
+
+    await tx.insert(membersTable).values({
+      organizationId,
+      userId,
+      role: 'owner'
+    })
+
+    await tx.insert(organizationSubscriptionsTable).values({ organizationId })
+
+    // Marker last, so a failed seed never blocks a retry.
+    await tx.insert(seedRunsTable).values({ id: SEED_RUN_MARKER_ID })
+  })
+
+  return { skipped: false }
+}
+
+if (import.meta.main) {
+  seedDatabase(db)
+    .then(result => {
+      if (result.skipped) console.info('Database already seeded; skipping.')
+      process.exit(0)
+    })
+    .catch(err => {
+      console.error('Error running seed:', err)
+      process.exit(1)
+    })
+}