create-ej-app 26.0.0 → 28.0.0

package/template/nextjs/src/emails/components/email-layout.tsx

@@ -1,8 +1,14 @@
+/**
+ * @fileoverview Shared email shell: a brand rule and name at the top, the
+ * content, and a copyright footer. Every template wraps its body in it.
+ *
+ * @module emails/components/email-layout
+ */
+
 import {
   Body,
   Container,
   Head,
-  Hr,
   Html,
   pixelBasedPreset,
   Preview,
@@ -11,7 +17,11 @@ import {
   Text
 } from 'react-email'
 
+/** Brand color. Email clients strip CSS variables, so it is a literal here. */
+const BRAND = '#171717'
+
 interface EmailLayoutProps {
+  /** Text email clients show in the inbox before the email is opened. */
   previewText: string
   companyName: string
   children: React.ReactNode
@@ -28,31 +38,37 @@ export default function EmailLayout({
       <Preview>{previewText}</Preview>
       <Tailwind
         config={{
-          presets: [pixelBasedPreset]
+          presets: [pixelBasedPreset],
+          theme: { extend: { colors: { brand: BRAND } } }
         }}
       >
         <Body className="bg-gray-100 font-sans">
           <Container className="mx-auto my-8 max-w-xl rounded-lg bg-white shadow-sm">
-            {/* Header */}
-            <Section className="rounded-t-lg bg-black px-8 py-6">
-              <Text className="m-0 text-center text-2xl font-bold text-white">
+            <Section
+              className="rounded-t-lg bg-white px-8 py-5"
+              style={{
+                borderTop: `4px solid ${BRAND}`,
+                borderBottom: '1px solid #E5E7EB'
+              }}
+            >
+              <Text className="m-0 text-lg font-bold tracking-tight text-gray-900">
                 {companyName}
               </Text>
             </Section>
 
-            {/* Content */}
             <Section className="px-8 py-6">{children}</Section>
 
-            {/* Footer */}
-            <Section className="rounded-b-lg bg-gray-50 px-8 py-6">
-              <Hr className="my-4 border-gray-200" />
+            <Section
+              className="rounded-b-lg bg-gray-50 px-8 py-6"
+              style={{ borderTop: '1px solid #E5E7EB' }}
+            >
               <Text className="m-0 text-center text-sm text-gray-500">
                 &copy; {new Date().getUTCFullYear()} {companyName}. All rights
                 reserved.
               </Text>
               <Text className="m-0 mt-2 text-center text-xs text-gray-400">
-                This is an automated email. Please do not reply directly to this
-                message.
+                This is an automated email. Replies to this address are not
+                read.
               </Text>
             </Section>
           </Container>

package/template/nextjs/src/emails/magic-link.tsx

@@ -1,49 +1,51 @@
 import { Button, Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 export interface MagicLinkEmailProps {
   magicLink: string
   companyName: string
 }
 
+/** Passwordless sign-in link. The link works once and expires in 5 minutes. */
 export default function MagicLinkEmail({
   magicLink,
   companyName
 }: MagicLinkEmailProps) {
-  const previewText = `Your magic link to sign in to ${companyName}`
-
   return (
-    <EmailLayout previewText={previewText} companyName={companyName}>
+    <EmailLayout
+      previewText={`Your link to sign in to ${companyName}`}
+      companyName={companyName}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
-        Sign in to {companyName}
+        Sign In to {companyName}
       </Heading>
 
       <Text className="mb-4 text-base text-gray-700">
-        Click the button below to securely sign in to your account. This link
-        will expire in 5 minutes.
+        Select the button below to sign in. The link expires in 5 minutes.
       </Text>
 
       <Button
         href={magicLink}
-        className="mb-4 rounded-lg bg-black px-6 py-3 text-center text-base font-semibold text-white no-underline"
+        className="bg-brand mb-4 rounded-lg px-6 py-3 text-center text-base font-semibold text-white no-underline"
       >
         Sign In
       </Button>
 
       <Text className="mb-4 text-sm text-gray-600">
-        Or copy and paste this link into your browser:
+        Or copy this link into your browser:
       </Text>
 
-      <Text className="mb-4 text-sm break-all text-blue-600">{magicLink}</Text>
+      <Text className="text-brand mb-4 text-sm break-all">{magicLink}</Text>
 
       <Text className="text-sm text-gray-500">
-        If you didn't request this email, you can safely ignore it.
+        If you didn&apos;t ask to sign in, you can ignore this email.
       </Text>
     </EmailLayout>
   )
 }
 
 MagicLinkEmail.PreviewProps = {
-  magicLink: 'https://example.com/magic-link?token=abc123',
-  companyName: 'Example Site'
+  magicLink: 'https://example.com/magic-link?token=your_magic_link_token_here',
+  companyName: siteConfig.name
 } satisfies MagicLinkEmailProps

package/template/nextjs/src/emails/test.tsx

@@ -1,25 +1,27 @@
 import { Button, Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 interface TestEmailProps {
   name: string
 }
 
+/** Sent by `bun run email:test` to check SMTP settings. */
 export default function TestEmail({ name }: TestEmailProps) {
   return (
-    <EmailLayout previewText="This is a test email" companyName="Test">
+    <EmailLayout
+      previewText="Test email from your app"
+      companyName={siteConfig.name}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
         Test Email for {name}
       </Heading>
-      <Text className="mb-4 text-base text-gray-700">
-        This is a test email template to verify email functionality.
-      </Text>
       <Text className="mb-6 text-base text-gray-700">
-        If you're seeing this, the email system is working correctly.
+        Your SMTP settings work: this email reached your inbox.
       </Text>
       <Button
         href="https://example.com"
-        className="rounded-md bg-black px-5 py-3 text-center text-sm font-medium text-white"
+        className="bg-brand rounded-md px-5 py-3 text-center text-sm font-medium text-white"
       >
         Test Button
       </Button>
@@ -28,5 +30,5 @@ export default function TestEmail({ name }: TestEmailProps) {
 }
 
 TestEmail.PreviewProps = {
-  name: 'John Doe'
-}
+  name: 'Alex Morgan'
+} satisfies TestEmailProps

package/template/nextjs/src/emails/welcome.tsx

@@ -1,34 +1,37 @@
 import { Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 export interface WelcomeEmailProps {
   userName: string
   companyName: string
 }
 
+/** Sent once, right after an account is created. */
 export default function WelcomeEmail({
   userName,
   companyName
 }: WelcomeEmailProps) {
-  const previewText = `Welcome to ${companyName}! Your account has been created successfully.`
-
   return (
-    <EmailLayout previewText={previewText} companyName={companyName}>
+    <EmailLayout
+      previewText={`Welcome to ${companyName}. Your account is ready.`}
+      companyName={companyName}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
-        Welcome to {companyName}! 🎉
+        Welcome to {companyName}
       </Heading>
 
       <Text className="mb-4 text-base text-gray-700">Hi {userName},</Text>
 
       <Text className="mb-4 text-base text-gray-700">
-        Thank you for creating an account with us. We're thrilled to have you as
-        part of our community!
+        Your account is ready. Sign in any time with the email address this
+        message was sent to.
       </Text>
     </EmailLayout>
   )
 }
 
 WelcomeEmail.PreviewProps = {
-  userName: 'John Doe',
-  companyName: 'Example Site'
+  userName: 'Alex Morgan',
+  companyName: siteConfig.name
 } satisfies WelcomeEmailProps

package/template/nextjs/src/env.ts

@@ -15,7 +15,7 @@ export const env = createEnv({
     EMAIL_SERVER_USER: z.string(),
     EMAIL_SERVER_PASSWORD: z.string(),
     EMAIL_SERVER_HOST: z.string(),
-    EMAIL_SERVER_PORT: z.string(),
+    EMAIL_SERVER_PORT: z.coerce.number().int().min(1).max(65535),
     EMAIL_FROM: z.email()
   },
 

package/template/nextjs/src/hooks/use-mobile.ts

@@ -2,18 +2,20 @@ import * as React from 'react'
 
 const MOBILE_BREAKPOINT = 768
 
-export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+function subscribe(onStoreChange: () => void) {
+  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+  mql.addEventListener('change', onStoreChange)
+  return () => mql.removeEventListener('change', onStoreChange)
+}
+
+function getSnapshot() {
+  return window.innerWidth < MOBILE_BREAKPOINT
+}
 
-  React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
-    const onChange = () => {
-      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    }
-    mql.addEventListener('change', onChange)
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    return () => mql.removeEventListener('change', onChange)
-  }, [])
+function getServerSnapshot() {
+  return false
+}
 
-  return !!isMobile
+export function useIsMobile() {
+  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
 }

package/template/nextjs/src/instrumentation.ts

@@ -5,12 +5,25 @@ import {
   SimpleSpanProcessor
 } from '@opentelemetry/sdk-trace-base'
 import { registerOTel } from '@vercel/otel'
+import { siteConfig } from '~/lib/siteConfig'
 
+/**
+ * Custom SpanProcessor that samples spans to reduce telemetry volume.
+ * Exports every error span, exports every span slower than 5s.
+ */
 class SmartSamplingSpanProcessor extends SimpleSpanProcessor {
+  /**
+   * Called when a span ends. Evaluates whether the span should be exported based on its properties.
+   *
+   * @param span - The readable span that has just ended
+   */
   onEnd(span: ReadableSpan): void {
     const isError = span.status.code === SpanStatusCode.ERROR
+    // span.duration is [seconds, nanoseconds]
+    // Spans slower than 5s
     const isSlow = span.duration[0] * 1000 + span.duration[1] / 1e6 > 5000
-    const isLucky = Math.random() < 0 // Adjust this value to adjust the sampling rate for non-error and non-slow spans
+    // Random sampling: Adjust probability as needed (e.g. 0.1 for 10%)
+    const isLucky = Math.random() < 0 // Currently disabled for non-essential traces
 
     if (isError || isSlow || isLucky) {
       super.onEnd(span)
@@ -18,9 +31,14 @@ class SmartSamplingSpanProcessor extends SimpleSpanProcessor {
   }
 }
 
+/**
+ * Registers OpenTelemetry instrumentation for the application.
+ * This function should be exported as `register` from `src/instrumentation.ts`
+ * to be automatically picked up by Next.js.
+ */
 export function register() {
   registerOTel({
-    serviceName: 'my-nextjs-app',
+    serviceName: siteConfig.name,
     spanProcessors: [new SmartSamplingSpanProcessor(new ConsoleSpanExporter())]
   })
 }

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

@@ -0,0 +1,55 @@
+/**
+ * Reusable Zod fragments for paginated, sortable list actions.
+ */
+import { z } from 'zod'
+import { SortOrderEnum } from '~/components/data-table/enum'
+
+/**
+ * Returns a reusable Zod schema fragment for cursor-less offset pagination.
+ *
+ * - `page`: 1-based page number (defaults to 1)
+ * - `limit`: Number of items per page; clamped between 10 and 100 (defaults to `defaultPageSize`)
+ *
+ * Spread the returned object into a `z.object({})` call to add pagination
+ * to any query schema.
+ *
+ * @param defaultPageSize - Default number of items per page (defaults to 10)
+ *
+ * @example
+ * z.object({
+ *   ...getPaginationSchema(20),
+ *   ...getSortSchema(['title', 'createdAt'])
+ * })
+ */
+export const getPaginationSchema = (defaultPageSize = 10) => ({
+  page: z.coerce.number().int().positive().optional().default(1),
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .min(10)
+    .max(100)
+    .optional()
+    .default(defaultPageSize)
+})
+
+/**
+ * Generates a reusable Zod schema fragment for sort parameters.
+ *
+ * @param keys - A non-empty tuple of the allowed `sortBy` field names for
+ *               the resource (e.g. `['title', 'createdAt', 'updatedAt']`).
+ * @returns An object with `sortOrder` and `sortBy` Zod validators that can
+ *          be spread into a `z.object({})` query schema.
+ *
+ * @example
+ * z.object({
+ *   ...paginationSchema,
+ *   ...getSortSchema(['title', 'createdAt', 'updatedAt'])
+ * })
+ */
+export const getSortSchema = <T extends string>(
+  keys: readonly [T, ...T[]]
+) => ({
+  sortOrder: z.enum(SortOrderEnum).optional(),
+  sortBy: z.enum(keys).optional()
+})

package/template/nextjs/src/lib/admin-navigation.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Admin panel navigation, shared by the sidebar and the
+ * command search.
+ *
+ * @module lib/admin-navigation
+ */
+
+import { Home, Users } from 'lucide-react'
+import { SidebarNavGroup } from '~/components/navigation-sidebar'
+
+const adminNavigation: SidebarNavGroup[] = [
+  {
+    label: 'Overview',
+    items: [
+      {
+        title: 'Dashboard',
+        url: '/admin',
+        exact: true,
+        icon: Home
+      }
+    ]
+  },
+  {
+    label: 'Settings',
+    superadminOnly: true,
+    items: [
+      {
+        title: 'Users & Roles',
+        url: '/admin/settings/users',
+        icon: Users
+      }
+    ]
+  }
+]
+
+/**
+ * The admin navigation visible to the current user. Superadmin-only groups
+ * are hidden from `admin` users.
+ */
+export const getAdminNavigation = (isSuperAdmin: boolean): SidebarNavGroup[] =>
+  isSuperAdmin
+    ? adminNavigation
+    : adminNavigation.filter(group => !group.superadminOnly)

package/template/nextjs/src/lib/auth-client.ts

@@ -1,5 +1,9 @@
 'use client'
 
+/**
+ * Browser auth client. The admin plugin gets the same access control as the
+ * server so `admin.hasPermission` checks agree on both sides.
+ */
 import {
   adminClient,
   inferAdditionalFields,
@@ -8,13 +12,20 @@ import {
 } from 'better-auth/client/plugins'
 import { createAuthClient } from 'better-auth/react'
 import type { auth } from './auth'
+import { ac, roles } from './auth-permissions'
 
-export const { signIn, signOut, useSession, getLastUsedLoginMethod } =
-  createAuthClient({
-    plugins: [
-      inferAdditionalFields<typeof auth>(),
-      magicLinkClient(),
-      adminClient(),
-      lastLoginMethodClient()
-    ]
-  })
+export const {
+  signIn,
+  signOut,
+  useSession,
+  updateUser,
+  getLastUsedLoginMethod,
+  admin
+} = createAuthClient({
+  plugins: [
+    inferAdditionalFields<typeof auth>(),
+    magicLinkClient(),
+    adminClient({ ac, roles }),
+    lastLoginMethodClient()
+  ]
+})

package/template/nextjs/src/lib/auth-permissions.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Access-control definitions for the Better Auth admin plugin.
+ *
+ * The platform has three roles:
+ *
+ * - `superadmin`: full control of the admin panel. Can list, view, create,
+ *   update, change the role of, ban and impersonate any user (including other
+ *   admins and superadmins).
+ * - `admin`: can open the admin panel and work with the pages you add
+ *   there, but is intentionally granted no user-management or impersonation
+ *   permissions.
+ * - `user`: a regular customer with no admin-panel access
+ *
+ * These statements/roles are shared by both the server (`auth.ts`) and the
+ * client (`auth-client.ts`) so permission checks stay consistent everywhere.
+ *
+ * @module lib/auth-permissions
+ */
+
+import { createAccessControl } from 'better-auth/plugins/access'
+import { defaultStatements } from 'better-auth/plugins/admin/access'
+
+/**
+ * The full set of permissions available across the admin panel.
+ *
+ * `defaultStatements` contributes the admin plugin's built-in `user` and
+ * `session` resources.
+ */
+export const statement = { ...defaultStatements } as const
+
+export const ac = createAccessControl(statement)
+
+/** Regular customer with no admin-panel privileges. */
+export const user = ac.newRole({})
+
+/**
+ * Operational admin who can open the admin panel but has no
+ * `user` or `session` permissions. User management and impersonation are
+ * therefore denied.
+ */
+export const admin = ac.newRole({})
+
+/**
+ * Full-control admin who receives every built-in user/session permission,
+ * including `impersonate-admins`.
+ *
+ * Each resource is granted explicitly rather than spreading
+ * `defaultStatements` (which is the statement *definition*, not a grant).
+ * This way a newly added resource is denied by default until it is
+ * deliberately listed here.
+ */
+export const superadmin = ac.newRole({
+  user: [...defaultStatements.user],
+  session: [...defaultStatements.session]
+})
+
+/** Role map passed to the admin plugin on both server and client. */
+export const roles = { user, admin, superadmin }
+
+/** Roles that are allowed to reach the admin panel at all. */
+export const adminRoles = ['admin', 'superadmin'] as const

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

@@ -1,3 +1,5 @@
+import 'server-only'
+
 import { validateEmail } from '@ejekanshjain/simple-email-validator'
 import { createId } from '@paralleldrive/cuid2'
 import { APIError, betterAuth } from 'better-auth'
@@ -15,9 +17,18 @@ import {
   verificationsTable
 } from '~/db/schema'
 import { env } from '~/env'
+import { ac, adminRoles, roles } from './auth-permissions'
 import { sendMagicLinkEmail, sendWelcomeEmail } from './email-service'
 import { siteConfig } from './siteConfig'
 
+/**
+ * Better Auth configuration.
+ *
+ * Features:
+ * - Magic link email sign-in
+ * - OAuth (GitHub, Google) with account linking
+ * - Admin plugin with `user`, `admin`, and `superadmin` roles
+ */
 export const auth = betterAuth({
   database: drizzleAdapter(db, {
     provider: 'pg',
@@ -53,6 +64,11 @@ export const auth = betterAuth({
   databaseHooks: {
     user: {
       create: {
+        // Magic-link sign-up sends an empty name; fall back to the email's
+        // local part so greetings and avatars never render blank.
+        before: async user => ({
+          data: { ...user, name: user.name.trim() || user.email.split('@')[0]! }
+        }),
         after: async user => {
           try {
             await start(sendWelcomeEmail, [
@@ -85,7 +101,12 @@ export const auth = betterAuth({
         }
       }
     }),
-    admin(),
+    admin({
+      ac,
+      roles,
+      adminRoles: [...adminRoles],
+      defaultRole: 'user'
+    }),
     lastLoginMethod()
   ],
   hooks: {
@@ -109,6 +130,13 @@ export const auth = betterAuth({
   }
 })
 
+/**
+ * The current session, cached per request.
+ *
+ * Returns null when signed out. `isAdmin` is true for both `admin` and
+ * `superadmin` (admin panel access). `isSuperAdmin` is true only for
+ * `superadmin` (user management, role changes, and impersonation).
+ */
 export const getAuthSession = cache(async () => {
   const authSession = await auth.api.getSession({
     headers: await headers()
@@ -116,7 +144,9 @@ export const getAuthSession = cache(async () => {
 
   if (!authSession || !authSession.user || !authSession.session) return null
 
-  const isAdmin = authSession.user.role === 'admin'
+  const role = authSession.user.role
+  const isSuperAdmin = role === 'superadmin'
+  const isAdmin = role === 'admin' || isSuperAdmin
 
-  return { ...authSession, isAdmin }
+  return { ...authSession, isAdmin, isSuperAdmin }
 })

package/template/nextjs/src/lib/callback-url.ts

@@ -0,0 +1,28 @@
+/** Origin used only to resolve a candidate callback and check where it lands. */
+const RESOLUTION_ORIGIN = 'https://callback.invalid'
+
+/**
+ * Narrow a caller-supplied `?callbackUrl=` down to a same-origin path.
+ *
+ * Returns the normalised path, or null when the value could leave the site.
+ * A leading `/` is not enough on its own: `//evil.com`, `/\evil.com`, and
+ * `/<tab>/evil.com` all resolve cross-origin in a browser, the last because
+ * URL parsing strips tabs and newlines first. The shape checks below reject
+ * the known forms, and resolving against a throwaway origin catches the rest.
+ */
+export function sanitizeCallbackUrl(
+  value: string | string[] | undefined
+): string | null {
+  if (typeof value !== 'string') return null
+  if (!/^\/(?![/\\])/.test(value)) return null
+  if (/[\t\n\r]/.test(value)) return null
+
+  try {
+    const resolved = new URL(value, RESOLUTION_ORIGIN)
+    if (resolved.origin !== RESOLUTION_ORIGIN) return null
+
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`
+  } catch {
+    return null
+  }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Application-wide constants for configuration and validation.
+ *
+ * Read limits, labels, and repeated values from here in the UI, validation,
+ * tests, and docs, so one change updates every place.
+ *
+ * @module lib/constants
+ */
+
+// ============================================
+// REQUEST ARRAY BOUNDS
+// ============================================
+
+/*
+ * Ceilings for arrays that reach SQL as an `IN (…)` list. Postgres caps a
+ * statement at 65535 bind parameters, and an unbounded array also builds in
+ * server memory first.
+ */
+
+/** Values accepted in one list-filter array, such as status facets */
+export const MAX_FILTER_VALUES = 100

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

@@ -1,2 +1,12 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * Useful for adding delays in async functions or testing
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * await delay(1000) // Wait 1 second
+ */
 export const delay = (ms: number) =>
   new Promise(resolve => setTimeout(resolve, ms))