create-ej-app 26.0.0 → 28.0.0

package/template/saas-starter/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/saas-starter/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/saas-starter/src/lib/actions.ts

@@ -1,6 +1,26 @@
+/**
+ * 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
@@ -13,6 +33,20 @@ export const getPaginationSchema = (defaultPageSize = 10) => ({
     .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[]]
 ) => ({

package/template/saas-starter/src/lib/admin-navigation.ts

@@ -1,4 +1,11 @@
-import { Home, Users } from 'lucide-react'
+/**
+ * @fileoverview Admin panel navigation, shared by the sidebar and the
+ * command search.
+ *
+ * @module lib/admin-navigation
+ */
+
+import { Home, MessageCircle, MessageSquare, Ticket, Users } from 'lucide-react'
 import { SidebarNavGroup } from '~/components/navigation-sidebar'
 
 const adminNavigation: SidebarNavGroup[] = [
@@ -13,8 +20,29 @@ const adminNavigation: SidebarNavGroup[] = [
       }
     ]
   },
+  {
+    label: 'Customers',
+    items: [
+      {
+        title: 'Support Tickets',
+        url: '/admin/support-tickets',
+        icon: Ticket
+      },
+      {
+        title: 'Feedback',
+        url: '/admin/feedbacks',
+        icon: MessageCircle
+      },
+      {
+        title: 'Contact Leads',
+        url: '/admin/contact-leads',
+        icon: MessageSquare
+      }
+    ]
+  },
   {
     label: 'Settings',
+    superadminOnly: true,
     items: [
       {
         title: 'Users & Roles',
@@ -25,6 +53,10 @@ const adminNavigation: SidebarNavGroup[] = [
   }
 ]
 
+/**
+ * The admin navigation visible to the current user. Superadmin-only groups
+ * are hidden from `admin` users.
+ */
 export const getAdminNavigation = (isSuperAdmin: boolean): SidebarNavGroup[] =>
   isSuperAdmin
     ? adminNavigation

package/template/saas-starter/src/lib/app-navigation.ts

@@ -1,58 +1,62 @@
-import { CreditCard, Home, Settings, Users } from 'lucide-react'
+import { CreditCard, Home, Settings, Ticket, Users } from 'lucide-react'
 import { SidebarNavGroup } from '~/components/navigation-sidebar'
+import { isManagerRole } from './rbac'
 
-export type UserOrganization = {
-  id: string
-  name: string
-  slug: string
-  logo: string | null
+/**
+ * Sidebar and command-search entries for one organization. Managers (owner
+ * and admin) also get support and settings pages.
+ */
+export function getAppNavigation(
+  organizationId: string,
   role: string
-  userId: string
-  memberId: string
-}
-
-export const canManageOrganization = (role: string): boolean =>
-  role === 'owner' || role === 'admin'
-
-export const getAppNavigation = (
-  orgId: string,
-  role: string
-): SidebarNavGroup[] => {
+): SidebarNavGroup[] {
   const groups: SidebarNavGroup[] = [
     {
-      label: 'Overview',
+      label: 'Workspace',
       items: [
         {
           title: 'Dashboard',
-          url: `/app/${orgId}/dashboard`,
+          url: `/app/${organizationId}/dashboard`,
           icon: Home
         }
       ]
     }
   ]
 
-  if (canManageOrganization(role)) {
-    groups.push({
-      label: 'Settings',
-      items: [
-        {
-          title: 'General',
-          url: `/app/${orgId}/settings`,
-          icon: Settings,
-          exact: true
-        },
-        {
-          title: 'Members',
-          url: `/app/${orgId}/settings/members`,
-          icon: Users
-        },
-        {
-          title: 'Billing',
-          url: `/app/${orgId}/settings/billing`,
-          icon: CreditCard
-        }
-      ]
-    })
+  if (isManagerRole(role)) {
+    groups.push(
+      {
+        label: 'Help',
+        items: [
+          {
+            title: 'Support',
+            url: `/app/${organizationId}/support-tickets`,
+            icon: Ticket
+          }
+        ]
+      },
+      {
+        label: 'Settings',
+        items: [
+          {
+            title: 'General',
+            url: `/app/${organizationId}/settings`,
+            icon: Settings,
+            exact: true
+          },
+          {
+            title: 'Members',
+            url: `/app/${organizationId}/settings/members`,
+            icon: Users
+          },
+          {
+            title: 'Billing',
+            url: `/app/${organizationId}/settings/billing`,
+            icon: CreditCard
+          }
+        ]
+      }
+    )
   }
 
   return groups

package/template/saas-starter/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,
@@ -9,20 +13,21 @@ 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,
+  updateUser,
   getLastUsedLoginMethod,
   admin,
-  organization,
-  useListOrganizations
+  organization
 } = createAuthClient({
   plugins: [
     inferAdditionalFields<typeof auth>(),
     magicLinkClient(),
-    adminClient(),
+    adminClient({ ac, roles }),
     organizationClient(),
     lastLoginMethodClient()
   ]

package/template/saas-starter/src/lib/auth-permissions.ts

@@ -1,22 +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 customer-facing data
+ *   (support tickets, feedback, and contact leads), 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'
 
-const statement = {
-  ...defaultStatements
-} as const
+/**
+ * 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)
 
-const user = ac.newRole({})
+/** Regular customer with no admin-panel privileges. */
+export const user = ac.newRole({})
 
-const admin = ac.newRole({
-  user: ['list', 'ban', 'impersonate', 'set-password', 'get', 'update'],
-  session: defaultStatements.session
-})
+/**
+ * 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({})
 
-const superadmin = ac.newRole({
-  user: defaultStatements.user,
-  session: defaultStatements.session
+/**
+ * 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/saas-starter/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'
@@ -9,7 +11,8 @@ import {
   magicLink,
   organization
 } from 'better-auth/plugins'
-import { eq } from 'drizzle-orm'
+import { and, count, eq, isNull, ne } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
 import { headers } from 'next/headers'
 import { cache } from 'react'
 import { start } from 'workflow/api'
@@ -18,23 +21,77 @@ import {
   accountsTable,
   invitationsTable,
   membersTable,
-  organizationsTable,
   organizationSubscriptionsTable,
+  organizationsTable,
   sessionsTable,
   usersTable,
   verificationsTable
 } from '~/db/schema'
 import { env } from '~/env'
-import { ac, roles } from './auth-permissions'
+import { ac, adminRoles, roles } from './auth-permissions'
+import {
+  INVITATION_EXPIRES_IN_DAYS,
+  MAX_ORGANIZATIONS_PER_USER
+} from './constants'
 import {
   sendInvitationEmail,
   sendMagicLinkEmail,
   sendWelcomeEmail
 } from './email-service'
-import { getOrganizationPlanCached } from './organization-plan-limits'
+import { getOrganizationPlan } from './plan-limits'
 import { siteConfig } from './siteConfig'
+import { deleteOrganizationUploads } from './storage'
 import { stripeClient } from './stripe'
 
+/**
+ * Blocks organization logos set through the Better Auth client. Logos go
+ * through `updateOrganizationAction`, which checks the upload belongs to the
+ * organization before saving it.
+ */
+function rejectClientLogo(logo: string | null | undefined) {
+  if (logo) {
+    throw new APIError('BAD_REQUEST', {
+      message: 'Change the logo from the organization settings page.'
+    })
+  }
+}
+
+/** True when `userId` is the only owner of at least one organization. */
+async function ownsOrganizationAlone(userId: string): Promise<boolean> {
+  const otherOwners = alias(membersTable, 'other_owners')
+
+  const [row] = await db
+    .select({ organizationId: membersTable.organizationId })
+    .from(membersTable)
+    .leftJoin(
+      otherOwners,
+      and(
+        eq(otherOwners.organizationId, membersTable.organizationId),
+        eq(otherOwners.role, 'owner'),
+        ne(otherOwners.userId, userId)
+      )
+    )
+    .where(
+      and(
+        eq(membersTable.userId, userId),
+        eq(membersTable.role, 'owner'),
+        isNull(otherOwners.id)
+      )
+    )
+    .limit(1)
+
+  return Boolean(row)
+}
+
+/**
+ * Better Auth configuration.
+ *
+ * Features:
+ * - Magic link email sign-in
+ * - OAuth (GitHub, Google) with account linking
+ * - Admin plugin with `user`, `admin`, and `superadmin` roles
+ * - Organization plugin with owner, admin, and member roles
+ */
 export const auth = betterAuth({
   database: drizzleAdapter(db, {
     provider: 'pg',
@@ -73,6 +130,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, [
@@ -86,6 +148,16 @@ export const auth = betterAuth({
             console.error('Failed to send welcome email:', error)
           }
         }
+      },
+      delete: {
+        before: async user => {
+          if (await ownsOrganizationAlone(user.id)) {
+            throw new APIError('BAD_REQUEST', {
+              message:
+                'This user is the only owner of an organization. Transfer ownership or delete the organization first.'
+            })
+          }
+        }
       }
     }
   },
@@ -107,20 +179,29 @@ export const auth = betterAuth({
     }),
     admin({
       ac,
-      roles
+      roles,
+      adminRoles: [...adminRoles],
+      defaultRole: 'user'
     }),
     organization({
-      organizationLimit: 10,
-      invitationExpiresIn: 7 * 24 * 60 * 60, // 7 days
+      organizationLimit: MAX_ORGANIZATIONS_PER_USER,
+      invitationExpiresIn: INVITATION_EXPIRES_IN_DAYS * 24 * 60 * 60,
       cancelPendingInvitationsOnReInvite: true,
-      sendInvitationEmail: async ({ id, email, organization, inviter }) => {
+      sendInvitationEmail: async ({
+        id,
+        email,
+        role,
+        organization,
+        inviter
+      }) => {
         try {
           await start(sendInvitationEmail, [
             email,
             {
               inviterName: inviter.user.name,
               organizationName: organization.name,
-              inviteLink: `${env.BETTER_AUTH_URL}/accept-invitation/${id}`,
+              inviteUrl: `${env.BETTER_AUTH_URL}/accept-invitation/${id}`,
+              role,
               companyName: siteConfig.name
             }
           ])
@@ -129,17 +210,28 @@ export const auth = betterAuth({
         }
       },
       organizationHooks: {
+        beforeCreateOrganization: async ({ organization }) => {
+          rejectClientLogo(organization.logo)
+        },
         afterCreateOrganization: async ({ organization }) => {
           await db.insert(organizationSubscriptionsTable).values({
             organizationId: organization.id
           })
         },
+        beforeUpdateOrganization: async ({ organization }) => {
+          rejectClientLogo(organization.logo)
+        },
+        // Files go first: if R2 fails, the organization and its paid plan
+        // both stay intact. Stripe is cancelled only once nothing else can fail.
         beforeDeleteOrganization: async ({ organization }) => {
+          await deleteOrganizationUploads(organization.id)
+
           const sub = await db.query.organizationSubscriptionsTable.findFirst({
             where: eq(
               organizationSubscriptionsTable.organizationId,
               organization.id
-            )
+            ),
+            columns: { stripeSubscriptionId: true }
           })
 
           if (sub?.stripeSubscriptionId) {
@@ -147,29 +239,31 @@ export const auth = betterAuth({
               await stripeClient.subscriptions.cancel(sub.stripeSubscriptionId)
             } catch (error) {
               console.error(
-                `Failed to cancel Stripe subscription ${sub.stripeSubscriptionId} for org ${organization.id} on org delete:`,
+                `Failed to cancel Stripe subscription ${sub.stripeSubscriptionId} while deleting organization ${organization.id}:`,
                 error
               )
               throw new APIError('BAD_REQUEST', {
                 message:
-                  'Could not cancel the active subscription. Please try again later.'
+                  'We could not cancel the active subscription, so the organization was kept. Try again in a few minutes.'
               })
             }
           }
-
-          await db
-            .delete(organizationSubscriptionsTable)
-            .where(
-              eq(organizationSubscriptionsTable.organizationId, organization.id)
-            )
         }
       },
+      // Better Auth caps pending invitations at this number, so leave room
+      // only for the seats current members do not fill.
       invitationLimit: async ({ organization }) => {
-        const { plan } = await getOrganizationPlanCached(organization.id)
-        return plan.maxMembers
+        const [{ plan }, [row]] = await Promise.all([
+          getOrganizationPlan(organization.id),
+          db
+            .select({ count: count() })
+            .from(membersTable)
+            .where(eq(membersTable.organizationId, organization.id))
+        ])
+        return Math.max(0, plan.maxMembers - (row?.count ?? 0))
       },
       membershipLimit: async (_, organization) => {
-        const { plan } = await getOrganizationPlanCached(organization.id)
+        const { plan } = await getOrganizationPlan(organization.id)
         return plan.maxMembers
       }
     }),
@@ -196,6 +290,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()