create-ej-app 26.0.0 → 28.0.0

package/template/saas-starter/src/app/error.tsx

@@ -0,0 +1,37 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+import { useEffect } from 'react'
+import { RouteError } from '~/components/route-error'
+
+/**
+ * Root segment error boundary.
+ *
+ * Catches runtime errors in pages and nested layouts under the root layout.
+ * Does not catch errors thrown in the root layout itself; see `global-error.tsx`.
+ */
+export default function Error({
+  error,
+  unstable_retry
+}: {
+  error: Error & { digest?: string }
+  unstable_retry: () => void
+}) {
+  const pathname = usePathname()
+  const homeHref =
+    pathname?.startsWith('/admin') && pathname !== '/admin' ? '/admin' : '/'
+  const homeLabel = homeHref === '/admin' ? 'Back to Admin' : 'Go Home'
+
+  useEffect(() => {
+    console.error('Route error boundary:', error)
+  }, [error])
+
+  return (
+    <RouteError
+      error={error}
+      onRetry={unstable_retry}
+      homeHref={homeHref}
+      homeLabel={homeLabel}
+    />
+  )
+}

package/template/saas-starter/src/app/fonts/index.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Global font definitions shared across all route groups.
+ *
+ * Fonts are defined here in a single module so that `next/font/local` generates
+ * a stable CSS module hash regardless of which layout imports them. Defining
+ * fonts inside individual route-group layouts (e.g. `(marketing)` or `(admin)`)
+ * causes the server and client to produce different class name hashes, leading
+ * to React hydration mismatches.
+ *
+ * Usage:
+ *   import { geistMono, geistSans } from '~/app/fonts'
+ *   <body className={`${geistSans.variable} ${geistMono.variable}`}>
+ *
+ * @module app/fonts/index
+ */
+
+import localFont from 'next/font/local'
+
+/**
+ * Geist Sans - primary variable font for body and UI text.
+ *
+ * Exposed as the CSS custom property `--font-geist-sans` so it can be
+ * referenced in Tailwind via `font-sans`.
+ *
+ * @see https://vercel.com/font/sans
+ */
+export const geistSans = localFont({
+  src: '../fonts/geist-sans/Geist-Variable.woff2',
+  variable: '--font-geist-sans',
+  weight: '100 900'
+})
+
+/**
+ * Geist Mono - monospace variable font for code blocks, badges, and
+ * any UI element that benefits from fixed-width rendering.
+ *
+ * Exposed as the CSS custom property `--font-geist-mono`.
+ *
+ * `adjustFontFallback` is disabled because the automatic metric adjustment
+ * produces undesirable layout shifts with the custom fallback stack below.
+ *
+ * @see https://vercel.com/font/mono
+ */
+export const geistMono = localFont({
+  src: '../fonts/geist-mono/GeistMono-Variable.woff2',
+  variable: '--font-geist-mono',
+  adjustFontFallback: false,
+  fallback: [
+    'ui-monospace',
+    'SFMono-Regular',
+    'Roboto Mono',
+    'Menlo',
+    'Monaco',
+    'Liberation Mono',
+    'DejaVu Sans Mono',
+    'Courier New',
+    'monospace'
+  ],
+  weight: '100 900'
+})

package/template/saas-starter/src/app/global-error.tsx

@@ -0,0 +1,38 @@
+'use client'
+
+import { useEffect } from 'react'
+import { RouteError } from '~/components/route-error'
+import { siteConfig } from '~/lib/siteConfig'
+import { geistMono, geistSans } from './fonts'
+import './globals.css'
+
+/**
+ * Root layout error boundary.
+ *
+ * Replaces the entire root layout when an error is thrown there.
+ * Must define its own document shell (`html` / `body`) and styles.
+ */
+export default function GlobalError({
+  error,
+  unstable_retry
+}: {
+  error: Error & { digest?: string }
+  unstable_retry: () => void
+}) {
+  useEffect(() => {
+    console.error('Global error boundary:', error)
+  }, [error])
+
+  return (
+    <html
+      lang="en"
+      suppressHydrationWarning
+      className={`${geistSans.variable} ${geistMono.variable}`}
+    >
+      <body>
+        <title>This Page Failed to Load | {siteConfig.name}</title>
+        <RouteError error={error} onRetry={unstable_retry} />
+      </body>
+    </html>
+  )
+}

package/template/saas-starter/src/app/globals.css

@@ -28,6 +28,14 @@
   --color-chart-3: var(--chart-3);
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
+
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+
   --color-sidebar: var(--sidebar);
   --color-sidebar-foreground: var(--sidebar-foreground);
   --color-sidebar-primary: var(--sidebar-primary);
@@ -84,6 +92,13 @@
   --sidebar-accent-foreground: oklch(0.205 0 0);
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
+
+  --success: oklch(0.552 0.152 149.579);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.574 0.188 70.08);
+  --warning-foreground: oklch(1 0 0);
+  --info: oklch(0.569 0.165 254.624);
+  --info-foreground: oklch(1 0 0);
 }
 
 .dark {
@@ -119,6 +134,13 @@
   --sidebar-accent-foreground: oklch(0.985 0 0);
   --sidebar-border: oklch(1 0 0 / 10%);
   --sidebar-ring: oklch(0.556 0 0);
+
+  --success: oklch(0.723 0.192 149.579);
+  --success-foreground: oklch(0.145 0 0);
+  --warning: oklch(0.769 0.188 70.08);
+  --warning-foreground: oklch(0.205 0 0);
+  --info: oklch(0.707 0.165 254.624);
+  --info-foreground: oklch(0.205 0 0);
 }
 
 @layer base {
@@ -128,6 +150,7 @@
 
   html {
     @apply font-sans antialiased;
+    scroll-behavior: smooth;
   }
 
   body {
@@ -138,6 +161,12 @@
   [role='button']:not([disabled]) {
     cursor: pointer;
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    html {
+      scroll-behavior: auto;
+    }
+  }
 }
 
 @theme inline {

package/template/saas-starter/src/app/layout.tsx

@@ -1,27 +1,49 @@
-import type { Metadata } from 'next'
-import { Geist, Geist_Mono } from 'next/font/google'
+/**
+ * @fileoverview Root layout: document shell, fonts, metadata, and the
+ * client providers every page shares (TanStack Query, theme, tooltips,
+ * toasts, and the navigation progress bar).
+ *
+ * @module app/layout
+ */
+
+import type { Metadata, Viewport } from 'next'
 import { Loader } from '~/components/loader'
 import { ReactQueryProvider } from '~/components/react-query-provider'
 import { ScreenSize } from '~/components/screen-size'
 import { ThemeProvider } from '~/components/theme-provider'
 import { Toaster } from '~/components/ui/sonner'
+import { TooltipProvider } from '~/components/ui/tooltip'
 import { env } from '~/env'
 import { siteConfig } from '~/lib/siteConfig'
+import { geistMono, geistSans } from './fonts'
 import './globals.css'
 
-const geistSans = Geist({
-  variable: '--font-geist-sans',
-  subsets: ['latin']
-})
-
-const geistMono = Geist_Mono({
-  variable: '--font-geist-mono',
-  subsets: ['latin']
-})
-
 export const metadata: Metadata = {
-  title: siteConfig.name,
-  description: siteConfig.description
+  metadataBase: new URL(env.BETTER_AUTH_URL),
+  title: {
+    default: siteConfig.name,
+    template: `%s | ${siteConfig.name}`
+  },
+  description: siteConfig.description,
+  applicationName: siteConfig.name,
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    siteName: siteConfig.name,
+    description: siteConfig.description
+  },
+  twitter: {
+    card: 'summary_large_image',
+    description: siteConfig.description
+  }
+}
+
+/** Browser chrome colors, matching `--background` in globals.css. */
+export const viewport: Viewport = {
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#ffffff' },
+    { media: '(prefers-color-scheme: dark)', color: '#0a0a0a' }
+  ]
 }
 
 export default function RootLayout({
@@ -38,10 +60,12 @@ export default function RootLayout({
       <body>
         <ReactQueryProvider>
           <ThemeProvider>
-            <Loader />
-            {children}
-            {env.APP_ENV === 'development' ? <ScreenSize /> : null}
-            <Toaster />
+            <TooltipProvider>
+              <Loader />
+              {children}
+              {env.APP_ENV === 'development' ? <ScreenSize /> : null}
+              <Toaster />
+            </TooltipProvider>
           </ThemeProvider>
         </ReactQueryProvider>
       </body>
@@ -49,5 +73,5 @@ export default function RootLayout({
   )
 }
 
-/** Forces dynamic rendering - page will be re-rendered on each request */
+/** Renders every request dynamically, so env-driven metadata stays current. */
 export const dynamic = 'force-dynamic'

package/template/saas-starter/src/app/not-found.tsx

@@ -1,12 +1,34 @@
+/**
+ * @fileoverview 404 Not Found Page
+ *
+ * Global catch-all page displayed when a route is not found.
+ * Redirects users back to the appropriate home page based on the current route context.
+ *
+ * **Behavior:**
+ * - Admin routes (/admin/*) redirect to /admin
+ * - All other routes redirect to /
+ *
+ * @module app/not-found
+ */
+
 'use client'
 
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
 import { Button } from '~/components/ui/button'
 
+/**
+ * Not Found Page Component
+ *
+ * Displays a 404 error message with context-aware home button.
+ * Uses the current pathname to determine the appropriate home route.
+ *
+ * @returns {JSX.Element} 404 error page with navigation button
+ */
 export default function NotFound() {
   const pathname = usePathname()
-  const homeRoute = pathname?.startsWith('/admin') ? '/admin' : '/'
+  const homeRoute =
+    pathname?.startsWith('/admin') && pathname !== '/admin' ? '/admin' : '/'
 
   return (
     <main className="bg-background text-foreground flex min-h-screen flex-col">
@@ -15,10 +37,10 @@ export default function NotFound() {
           <h1 className="text-foreground mb-2 text-6xl font-bold">404</h1>
           <p className="text-muted-foreground mb-8 text-xl">Page not found</p>
           <p className="text-muted-foreground mb-8 max-w-md text-base">
-            The page you're looking for doesn't exist.
+            The page you&apos;re looking for doesn&apos;t exist.
           </p>
           <Button asChild>
-            <Link href={homeRoute}>Return to Home</Link>
+            <Link href={homeRoute}>Return Home</Link>
           </Button>
         </div>
       </section>

package/template/saas-starter/src/app/robots.ts

@@ -1,19 +1,16 @@
 import type { MetadataRoute } from 'next'
 import { env } from '~/env'
 
+/** Renders every request dynamically, so the environment check is live. */
 export const dynamic = 'force-dynamic'
 
+/**
+ * robots.txt. Staging blocks every crawler; production keeps signed-in
+ * surfaces and the API out of search results.
+ */
 export default function robots(): MetadataRoute.Robots {
-  // Block all crawlers in staging to prevent accidental indexing
   if (env.APP_ENV === 'staging') {
-    return {
-      rules: [
-        {
-          userAgent: '*',
-          disallow: '/'
-        }
-      ]
-    }
+    return { rules: [{ userAgent: '*', disallow: '/' }] }
   }
 
   const baseUrl = env.BETTER_AUTH_URL
@@ -23,7 +20,14 @@ export default function robots(): MetadataRoute.Robots {
       {
         userAgent: '*',
         allow: '/',
-        disallow: ['/api/', '/admin/', '/app/', '/accept-invitation/']
+        disallow: [
+          '/api/',
+          '/admin',
+          '/app',
+          '/accept-invitation',
+          '/profile',
+          '/support'
+        ]
       }
     ],
     sitemap: `${baseUrl}/sitemap.xml`,

package/template/saas-starter/src/app/sitemap.ts

@@ -3,13 +3,14 @@ import { env } from '~/env'
 
 export const dynamic = 'force-dynamic'
 
+/** Public pages only. Staging returns an empty sitemap. */
 export default function sitemap(): MetadataRoute.Sitemap {
   if (env.APP_ENV === 'staging') return []
 
   const baseUrl = env.BETTER_AUTH_URL
   const lastModified = new Date()
 
-  const routes = ['/', '/privacy', '/terms', '/login']
+  const routes = ['/', '/contact-us', '/privacy', '/terms', '/login']
 
   return routes.map(path => ({
     url: `${baseUrl}${path === '/' ? '' : path}`,

package/template/saas-starter/src/components/confirm-dialog.tsx

@@ -0,0 +1,79 @@
+'use client'
+
+import { Loader2 } from 'lucide-react'
+import type { ReactNode } from 'react'
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle
+} from '~/components/ui/alert-dialog'
+import { Button } from '~/components/ui/button'
+
+/**
+ * Controlled confirmation for destructive or hard-to-undo actions. Use it
+ * instead of `window.confirm`.
+ *
+ * The dialog stays open while `pending` is true; close it from the
+ * caller's success handler by clearing whatever drives `open`.
+ *
+ * @example
+ * <ConfirmDialog
+ *   open={target !== null}
+ *   onOpenChange={open => !open && setTarget(null)}
+ *   title="Delete User"
+ *   description="This permanently deletes the account."
+ *   confirmLabel="Delete User"
+ *   pending={isDeleting}
+ *   onConfirm={() => deleteUser(target)}
+ * />
+ */
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  confirmLabel,
+  pending = false,
+  destructive = true,
+  onConfirm
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: string
+  description: ReactNode
+  confirmLabel: string
+  pending?: boolean
+  destructive?: boolean
+  onConfirm: () => void
+}) {
+  return (
+    <AlertDialog
+      open={open}
+      onOpenChange={next => {
+        if (!pending) onOpenChange(next)
+      }}
+    >
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={pending}>Cancel</AlertDialogCancel>
+          <Button
+            variant={destructive ? 'destructive' : 'default'}
+            disabled={pending}
+            onClick={onConfirm}
+          >
+            {pending ? <Loader2 className="animate-spin" /> : null}
+            {confirmLabel}
+          </Button>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}

package/template/saas-starter/src/components/dashboard-header.tsx

@@ -20,6 +20,8 @@ type DashboardHeaderProps = {
   actions?: ReactNode
   fallbackName?: string
   fallbackInitials?: string
+  isSuperAdmin?: boolean
+  isImpersonating?: boolean
 }
 
 export function DashboardHeader({
@@ -27,7 +29,9 @@ export function DashboardHeader({
   search,
   actions,
   fallbackName,
-  fallbackInitials
+  fallbackInitials,
+  isSuperAdmin,
+  isImpersonating
 }: DashboardHeaderProps) {
   return (
     <header className="bg-background sticky top-0 z-50 flex h-14 shrink-0 items-center gap-2 border-b px-4">
@@ -57,6 +61,8 @@ export function DashboardHeader({
           user={user}
           fallbackName={fallbackName}
           fallbackInitials={fallbackInitials}
+          isSuperAdmin={isSuperAdmin}
+          isImpersonating={isImpersonating}
         />
       </div>
     </header>

package/template/saas-starter/src/components/data-table/features.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared TanStack Table v9 feature set for the app DataTable.
+ *
+ * Defined once outside components so feature types stay stable and tree-shaken.
+ */
+import {
+  type ColumnDef,
+  type RowData,
+  columnVisibilityFeature,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  rowPaginationFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_alphanumericCaseSensitive,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  sortFn_textCaseSensitive,
+  tableFeatures
+} from '@tanstack/react-table'
+
+/** Features registered by every DataTable instance. */
+export const dataTableFeatures = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+  columnVisibilityFeature,
+  sortedRowModel: createSortedRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  sortFns: {
+    alphanumeric: sortFn_alphanumeric,
+    alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+    text: sortFn_text,
+    textCaseSensitive: sortFn_textCaseSensitive,
+    datetime: sortFn_datetime,
+    basic: sortFn_basic
+  }
+})
+
+type DataTableFeatures = typeof dataTableFeatures
+
+/**
+ * Column definition typed to the DataTable feature set.
+ * Prefer this over raw `ColumnDef` from `@tanstack/react-table`.
+ */
+export type DataTableColumnDef<
+  TData extends RowData,
+  TValue = unknown
+> = ColumnDef<DataTableFeatures, TData, TValue>