create-ej-app 25.0.0 → 27.0.0

package/template/nextjs/src/lib/safe-action.ts

@@ -1,30 +1,132 @@
+import 'server-only'
+
 import { createSafeActionClient } from 'next-safe-action'
 import { getAuthSession } from './auth'
-import { recordWideEvent } from './otel'
+import { AppError, AppErrorCode, isAppError } from './errors'
+import { flattenForWideEvent, recordError, recordWideEvent } from './otel'
+
+/** Shown for every unexpected error; details stay in telemetry. */
+export const UNEXPECTED_ERROR_MESSAGE =
+  'The request did not finish. Try again in a few minutes.'
+
+type ActionServerArgs = {
+  parsedInput?: unknown
+  clientInput?: unknown
+  [key: string]: unknown
+}
 
-export const actionClient = createSafeActionClient().use(
-  async ({ next, ctx }) => {
-    const authSession = await getAuthSession()
+/**
+ * Wrap a safe-action server function with wide-event telemetry.
+ *
+ * Records `action.name`, flattened `parsedInput` (or `clientInput`), and on
+ * success `outcome: 'success'` plus `duration_ms`. Failures keep error fields
+ * from `handleServerError`; duration is still recorded.
+ *
+ * @example
+ * export const myAction = authActionClient
+ *   .inputSchema(schema)
+ *   .action(
+ *     withWideEvent('myAction', async ({ parsedInput, ctx }) => {
+ *       // business logic only
+ *     })
+ *   )
+ */
+export function withWideEvent<TArgs extends ActionServerArgs, TResult>(
+  actionName: string,
+  serverCode: (args: TArgs) => Promise<TResult>
+): (args: TArgs) => Promise<TResult> {
+  return async args => {
+    const startedAt = Date.now()
+    const input = args.parsedInput ?? args.clientInput
+
+    recordWideEvent({
+      'action.name': actionName,
+      ...flattenForWideEvent(input, 'input')
+    })
 
-    if (authSession)
+    try {
+      const result = await serverCode(args)
       recordWideEvent({
-        'user.id': authSession.user.id,
-        'user.admin': authSession.isAdmin,
-        'session.id': authSession.session.id
+        outcome: 'success',
+        duration_ms: Date.now() - startedAt
       })
+      return result
+    } catch (error) {
+      recordWideEvent({
+        outcome: 'error',
+        duration_ms: Date.now() - startedAt
+      })
+      throw error
+    }
+  }
+}
 
-    return next({
-      ctx: {
-        ...ctx,
-        ...authSession
-      }
+/**
+ * Configured safe action client with authentication middleware
+ * This client wraps server actions with:
+ * - Automatic input/output validation using Zod
+ * - Type-safe error handling ({@link AppError} messages reach the client)
+ * - Server-side authentication injection
+ *
+ * All server actions using this client automatically receive the current auth session
+ * in the context, so protected actions can access user information.
+ *
+ * @example
+ * export const myAction = actionClient
+ *   .inputSchema(z.object({ name: z.string() }))
+ *   .action(async ({ parsedInput: { name }, ctx }) => {
+ *     const userId = ctx.user?.id // Auth injected automatically
+ *     return { success: true }
+ *   })
+ */
+export const actionClient = createSafeActionClient({
+  handleServerError(e) {
+    if (isAppError(e)) {
+      recordWideEvent({
+        'error.name': e.name,
+        'error.code': e.code,
+        'error.message': e.message,
+        'error.expected': true,
+        outcome: 'error'
+      })
+      return e.message
+    }
+
+    recordError(e)
+    recordWideEvent({
+      'error.name': e.name,
+      'error.expected': false,
+      'error.message': e.message,
+      outcome: 'error'
     })
+    return UNEXPECTED_ERROR_MESSAGE
   }
-)
+}).use(async ({ next, ctx }) => {
+  // Retrieve current authentication session
+  const authSession = await getAuthSession()
+
+  // Record user information in telemetry for all actions, if available
+  if (authSession) {
+    recordWideEvent({
+      'user.id': authSession.user.id,
+      'user.admin': authSession.isAdmin,
+      'user.superAdmin': authSession.isSuperAdmin,
+      'session.id': authSession.session.id
+    })
+  }
+
+  // Inject auth session into action context for all downstream actions
+  return next({
+    ctx: {
+      ...ctx,
+      ...authSession
+    }
+  })
+})
 
 export const authActionClient = actionClient.use(async ({ ctx, next }) => {
   if (!ctx?.user || !ctx?.session) {
-    throw new Error('Unauthorized')
+    throw new AppError(AppErrorCode.UNAUTHORIZED, 'Sign in to continue.')
   }
 
   return next({
@@ -36,9 +138,18 @@ export const authActionClient = actionClient.use(async ({ ctx, next }) => {
   })
 })
 
+/**
+ * Action client for the admin panel.
+ *
+ * Allows both `admin` and `superadmin` roles. Use for actions that any
+ * admin-panel user may run, such as reading customer data.
+ */
 export const adminActionClient = authActionClient.use(async ({ ctx, next }) => {
   if (!ctx.isAdmin) {
-    throw new Error('Forbidden')
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to do this.'
+    )
   }
 
   return next({
@@ -49,3 +160,28 @@ export const adminActionClient = authActionClient.use(async ({ ctx, next }) => {
     }
   })
 })
+
+/**
+ * Action client restricted to the `superadmin` role.
+ *
+ * Use for privileged operations, such as user management, role changes, and
+ * impersonation, that `admin` users cannot perform.
+ */
+export const superAdminActionClient = adminActionClient.use(
+  async ({ ctx, next }) => {
+    if (!ctx.isSuperAdmin) {
+      throw new AppError(
+        AppErrorCode.FORBIDDEN,
+        'You do not have permission to do this.'
+      )
+    }
+
+    return next({
+      ctx: {
+        ...ctx,
+        user: ctx.user,
+        session: ctx.session
+      }
+    })
+  }
+)

package/template/nextjs/src/lib/search.ts

@@ -0,0 +1,16 @@
+/**
+ * Escape characters that are special in SQL LIKE / ILIKE patterns.
+ *
+ * Postgres uses `\` as the default escape character. Without escaping, a
+ * user-typed `%` or `_` becomes a wildcard and can force full-table scans.
+ */
+export function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, char => `\\${char}`)
+}
+
+/**
+ * Build a case-insensitive contains pattern: `%value%` with wildcards escaped.
+ */
+export function likeContains(value: string): string {
+  return `%${escapeLikePattern(value)}%`
+}

package/template/nextjs/src/lib/seo.ts

@@ -0,0 +1,7 @@
+import type { Metadata } from 'next'
+
+/** Meta robots for authenticated or non-public surfaces. */
+export const privatePageRobots = {
+  index: false,
+  follow: false
+} satisfies NonNullable<Metadata['robots']>

package/template/nextjs/src/lib/siteConfig.ts

@@ -1,4 +1,20 @@
+/**
+ * @fileoverview Brand identity and site-wide copy.
+ *
+ * Layouts, emails, legal pages, and metadata read from here. Never hardcode
+ * the product name anywhere else.
+ *
+ * @module lib/siteConfig
+ */
 export const siteConfig = {
   name: 'Project Name',
-  description: 'Project Description'
+  description: 'Project Description',
+  logo: '/logo.svg',
+  logoDark: '/logo-dark.svg',
+  contact: {
+    email: 'hello@example.com'
+  },
+  legal: {
+    lastUpdated: 'September 25, 2026'
+  }
 }

package/template/nextjs/src/lib/toast-message.ts

@@ -2,14 +2,100 @@
 
 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 || 'Something went wrong. Please try again later.', {
+  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/nextjs/src/lib/validations.ts

@@ -0,0 +1,30 @@
+/**
+ * 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'
+
+/**
+ * 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()

package/template/nextjs/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/nextjs/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/nextjs/src/scripts/seed.ts

@@ -1,11 +1,62 @@
-const seedData = async () => {}
+/**
+ * @fileoverview Seeds a local database with a superadmin and a regular user.
+ *
+ * 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, 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!()
+
+    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'
+      }
+    ])
+
+    // 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/nextjs/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/nextjs/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')
+  })
+})