create-ej-app 26.0.0 → 28.0.0

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

@@ -1,12 +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()
-  .min(10)
   .max(20)
-  .regex(/^[\d+\-().\s]+$/)
+  .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/seed.ts

@@ -1,11 +1,85 @@
-const seedData = async () => {}
+/**
+ * @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) {
-  try {
-    await seedData()
-  } catch (err) {
-    console.error('Error seeding data:', err)
-  } finally {
-    process.exit(0)
-  }
+  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)
+    })
 }

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

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Installs Postgres functions and triggers that Drizzle cannot
+ * manage.
+ *
+ * Support tickets get a `TICKET-000001` number from a counter table. The
+ * counter function upserts atomically, and a BEFORE INSERT trigger fills in
+ * `ticket_number`, so inserts never pass the number themselves.
+ *
+ * Everything is CREATE OR REPLACE, so the script is safe to re-run.
+ * `bun run db:push` runs it before `drizzle-kit push`.
+ */
+
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+
+/** Installs every custom function and trigger on the given client. */
+export async function setupDatabase(database: typeof db = db): Promise<void> {
+  // INSERT ... ON CONFLICT ... DO UPDATE is one atomic statement, so two
+  // concurrent calls never receive the same number.
+  await database.execute(sql`
+    CREATE OR REPLACE FUNCTION get_next_support_ticket_number()
+    RETURNS TEXT AS $$
+    DECLARE
+        new_number INTEGER;
+    BEGIN
+        INSERT INTO support_ticket_counter (id, counter)
+        VALUES (1, 1)
+        ON CONFLICT (id)
+        DO UPDATE SET counter = support_ticket_counter.counter + 1
+        RETURNING counter INTO new_number;
+
+        RETURN 'TICKET-' || LPAD(new_number::TEXT, 6, '0');
+    END;
+    $$ LANGUAGE plpgsql;
+  `)
+
+  // An explicit ticket_number (seeding, migrations) skips the counter.
+  await database.execute(sql`
+    CREATE OR REPLACE FUNCTION trg_set_support_ticket_number()
+    RETURNS TRIGGER AS $$
+    BEGIN
+        IF NEW.ticket_number IS NULL OR NEW.ticket_number = '' THEN
+            NEW.ticket_number := get_next_support_ticket_number();
+        END IF;
+        RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `)
+
+  // On a fresh database this runs before drizzle-kit push, so create a stub
+  // table for the trigger to attach to. The push then adds the real columns.
+  await database.execute(sql`
+    CREATE TABLE IF NOT EXISTS support_tickets (
+      id TEXT PRIMARY KEY
+    );
+  `)
+
+  await database.execute(sql`
+    CREATE OR REPLACE TRIGGER set_support_ticket_number
+    BEFORE INSERT ON support_tickets
+    FOR EACH ROW EXECUTE FUNCTION trg_set_support_ticket_number();
+  `)
+}
+
+if (import.meta.main) {
+  setupDatabase(db)
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error running setup-db:', err)
+      process.exit(1)
+    })
+}

package/template/saas-starter/src/scripts/setup-stripe-plans.ts

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Creates the Stripe products, prices, and billing portal
+ * configuration for every paid plan in `~/lib/plans`.
+ *
+ * Existing prices are reused. New IDs are written to `stripe.txt`; copy them
+ * into `.env`, then delete the file.
+ */
 import { writeFile } from 'fs/promises'
 import type Stripe from 'stripe'
 import { env } from '~/env'
@@ -190,11 +197,10 @@ const setupPortalConfiguration = async (paidPlans: PaidPlanPrices[]) => {
 }
 
 if (import.meta.main) {
-  try {
-    await setupStripePlans()
-  } catch (err) {
-    console.error('Error setting up stripe plans:', err)
-  } finally {
-    process.exit(0)
-  }
+  setupStripePlans()
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error setting up Stripe plans:', err)
+      process.exit(1)
+    })
 }

package/template/saas-starter/src/scripts/test-mail.ts

@@ -1,35 +1,43 @@
+/**
+ * @fileoverview Sends one test email to check SMTP settings.
+ *
+ * @example
+ * ```bash
+ * bun run email:test you@example.com
+ * ```
+ */
+
 import { render, toPlainText } from '@react-email/render'
 import TestEmail from '~/emails/test'
 import { sendEmail } from '~/lib/nodemailer'
 
-async function sendTestMail() {
-  const html = await render(
-    TestEmail({
-      name: 'John Doe'
-    }),
-    {
-      pretty: true
-    }
-  )
-
-  const text = toPlainText(html)
+async function sendTestMail(to: string) {
+  const html = await render(TestEmail({ name: to }), { pretty: true })
 
   const result = await sendEmail({
-    to: 'john@example.com',
+    to,
     subject: 'Test Email',
-    text,
+    text: toPlainText(html),
     html
   })
 
-  console.info('Test email sent successfully', result)
+  console.info('Test email sent', result)
 }
 
 if (import.meta.main) {
-  try {
-    await sendTestMail()
-  } catch (err) {
-    console.error('Error sending test mail:', err)
-  } finally {
-    process.exit(0)
+  const to = process.argv[2]
+
+  if (!to) {
+    console.error(
+      'Pass a recipient address: bun run email:test you@example.com'
+    )
+    process.exit(1)
   }
+
+  sendTestMail(to)
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error sending test mail:', err)
+      process.exit(1)
+    })
 }

package/template/saas-starter/tests/admin/users.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, test } from 'bun:test'
+import { createUser, getUsers, updateUser } from '~/app/(admin)/actions/users'
+import {
+  asAnonymous,
+  asUser,
+  expectData,
+  expectServerError,
+  Fixtures
+} from '../helpers'
+
+describe('admin user management', () => {
+  const fx = new Fixtures()
+  afterEach(() => fx.cleanup())
+
+  test('signed-out and regular users cannot reach admin actions', async () => {
+    const user = await fx.user()
+
+    expectServerError(
+      await asAnonymous(() => getUsers({ page: 1, limit: 10 })),
+      'sign in'
+    )
+    expectServerError(
+      await asUser(user, () => getUsers({ page: 1, limit: 10 })),
+      'permission'
+    )
+  })
+
+  test('a superadmin cannot remove their own superadmin role', async () => {
+    const superadmin = await fx.platformUser('superadmin')
+
+    const result = await asUser(superadmin, () =>
+      updateUser({
+        id: superadmin.id,
+        name: superadmin.name,
+        email: superadmin.email,
+        role: 'admin'
+      })
+    )
+
+    expectServerError(result, 'your own superadmin role')
+  })
+
+  test('admins cannot manage users; superadmins can', async () => {
+    const admin = await fx.platformUser('admin')
+    const superadmin = await fx.platformUser('superadmin')
+
+    expectServerError(
+      await asUser(admin, () => getUsers({ page: 1, limit: 10 })),
+      'permission'
+    )
+    expectData(await asUser(superadmin, () => getUsers({ page: 1, limit: 10 })))
+  })
+
+  test('creating a user with a taken email explains the conflict', async () => {
+    const superadmin = await fx.platformUser('superadmin')
+    const existing = await fx.user()
+
+    const result = await asUser(superadmin, () =>
+      createUser({ name: 'Duplicate', email: existing.email, role: 'user' })
+    )
+
+    expectServerError(result, 'already uses this email')
+  })
+})

package/template/saas-starter/tests/db/fk-indexes.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+
+/**
+ * Postgres does not index foreign key columns automatically. Without an index,
+ * every cascade or SET NULL from the parent side sequentially scans the child
+ * table while holding row locks, so deleting one organization can stall the
+ * platform.
+ *
+ * This finds every FK whose leading column is not the leading column of any
+ * index, which is exactly the shape that degrades.
+ */
+const UNINDEXED_FOREIGN_KEYS = sql`
+  SELECT
+    c.conrelid::regclass::text AS table_name,
+    a.attname::text AS column_name
+  FROM pg_constraint c
+  JOIN pg_attribute a
+    ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+  WHERE c.contype = 'f'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM pg_index i
+      WHERE i.indrelid = c.conrelid
+        AND i.indkey[0] = c.conkey[1]
+    )
+  ORDER BY 1, 2
+`
+
+/** postgres-js returns a row array; PGlite returns `{ rows }`. */
+const toRows = <T>(result: unknown): T[] =>
+  Array.isArray(result)
+    ? (result as T[])
+    : ((result as { rows: T[] }).rows ?? [])
+
+describe('foreign key indexing', () => {
+  test('every foreign key column leads an index', async () => {
+    const rows = toRows<{ table_name: string; column_name: string }>(
+      await db.execute(UNINDEXED_FOREIGN_KEYS)
+    )
+
+    expect(rows.map(r => `${r.table_name}.${r.column_name}`)).toEqual([])
+  })
+
+  test('every foreign key declares an explicit delete rule', async () => {
+    const rows = toRows<{ table_name: string; constraint_name: string }>(
+      await db.execute(sql`
+        SELECT
+          c.conrelid::regclass::text AS table_name,
+          c.conname::text AS constraint_name
+        FROM pg_constraint c
+        WHERE c.contype = 'f' AND c.confdeltype = 'a'
+        ORDER BY 1, 2
+      `)
+    )
+
+    // confdeltype 'a' is NO ACTION, which is what an omitted onDelete leaves
+    // behind. Every FK should say cascade, set null, or restrict on purpose.
+    expect(rows.map(r => `${r.table_name}.${r.constraint_name}`)).toEqual([])
+  })
+})

package/template/saas-starter/tests/db/seed.test.ts

@@ -0,0 +1,57 @@
+import { PGlite } from '@electric-sql/pglite'
+import { describe, expect, test } from 'bun:test'
+import { pushSchema } from 'drizzle-kit/api'
+import { drizzle } from 'drizzle-orm/pglite'
+import * as relations from '~/db/relations'
+import * as schema from '~/db/schema'
+import { seedDatabase } from '~/scripts/seed'
+import { setupDatabase } from '~/scripts/setup-db'
+
+/**
+ * The seed writes straight through the schema, around Zod, so it exercises
+ * CHECK constraints, foreign keys, and triggers against realistic data.
+ *
+ * It runs on its own PGlite instance: seeded rows would otherwise leak into
+ * every other suite in the same worker and break their counts.
+ */
+describe('seed script', () => {
+  test('applies cleanly once, then skips', async () => {
+    // Same Emscripten proc_exit side effect as tests/setup/pglite-db.ts.
+    const exitCodeBeforePglite = process.exitCode
+
+    const client = new PGlite()
+    const db = drizzle({ client, schema: { ...schema, ...relations } })
+
+    const { apply, hasDataLoss } = await pushSchema(
+      schema,
+      db as unknown as Parameters<typeof pushSchema>[1]
+    )
+    expect(hasDataLoss).toBe(false)
+    await apply()
+    await setupDatabase(db as unknown as Parameters<typeof setupDatabase>[0])
+
+    const seed = () =>
+      seedDatabase(db as unknown as Parameters<typeof seedDatabase>[0])
+
+    expect((await seed()).skipped).toBe(false)
+
+    const [users, organizations, subscriptions] = await Promise.all([
+      db.select().from(schema.usersTable),
+      db.select().from(schema.organizationsTable),
+      db.select().from(schema.organizationSubscriptionsTable)
+    ])
+    expect(users.map(user => user.role).sort()).toEqual(['superadmin', 'user'])
+    expect(organizations).toHaveLength(1)
+    expect(subscriptions).toHaveLength(1)
+
+    expect((await seed()).skipped).toBe(true)
+    expect(await db.select().from(schema.usersTable)).toHaveLength(2)
+
+    if (process.exitCode === 99) {
+      process.exitCode =
+        exitCodeBeforePglite !== undefined && exitCodeBeforePglite !== 99
+          ? exitCodeBeforePglite
+          : 0
+    }
+  }, 120_000)
+})

package/template/saas-starter/tests/helpers/action.ts

@@ -0,0 +1,71 @@
+import { expect } from 'bun:test'
+import { UNEXPECTED_ERROR_MESSAGE } from '~/lib/safe-action'
+
+type ActionResult = {
+  data?: unknown
+  serverError?: string
+  validationErrors?: unknown
+}
+
+const MASKED = UNEXPECTED_ERROR_MESSAGE
+
+export function expectData<T>(
+  result: ActionResult | undefined
+): asserts result is { data: T } {
+  if (!result) throw new Error('Expected action result, got undefined')
+  if (result.serverError) {
+    throw new Error(`Expected success, got serverError: ${result.serverError}`)
+  }
+  if (result.validationErrors) {
+    throw new Error(
+      `Expected success, got validationErrors: ${JSON.stringify(result.validationErrors)}`
+    )
+  }
+  if (result.data === undefined) {
+    throw new Error('Expected action data, got undefined')
+  }
+}
+
+/** Action returned null/undefined data (some actions swallow errors). */
+export function expectNoData(result: ActionResult | undefined) {
+  expect(result?.data ?? null).toBeNull()
+}
+
+/** Action was rejected by its input schema, before any handler ran. */
+export function expectValidationError(result: ActionResult | undefined) {
+  if (!result?.validationErrors) {
+    throw new Error(
+      `Expected validationErrors, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  return result.validationErrors
+}
+
+/**
+ * Action failed with a serverError.
+ * next-safe-action can mask thrown Error messages as a generic string.
+ * In that case, this helper only asserts that a failure occurred.
+ */
+export function expectServerError(
+  result: ActionResult | undefined,
+  messageIncludes?: string | RegExp
+) {
+  if (!result?.serverError) {
+    throw new Error(
+      `Expected serverError, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  if (
+    messageIncludes &&
+    result.serverError.toLowerCase() !== MASKED.toLowerCase()
+  ) {
+    if (typeof messageIncludes === 'string') {
+      expect(result.serverError.toLowerCase()).toContain(
+        messageIncludes.toLowerCase()
+      )
+    } else {
+      expect(result.serverError).toMatch(messageIncludes)
+    }
+  }
+  return result.serverError
+}