create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/emails/magic-link.tsx

@@ -0,0 +1,51 @@
+import { Button, Heading, Text } from 'react-email'
+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) {
+  return (
+    <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}
+      </Heading>
+
+      <Text className="mb-4 text-base text-gray-700">
+        Select the button below to sign in. The link expires in 5 minutes.
+      </Text>
+
+      <Button
+        href={magicLink}
+        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 this link into your browser:
+      </Text>
+
+      <Text className="text-brand mb-4 text-sm break-all">{magicLink}</Text>
+
+      <Text className="text-sm text-gray-500">
+        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=your_magic_link_token_here',
+  companyName: siteConfig.name
+} satisfies MagicLinkEmailProps

package/template/saas-starter/src/emails/test.tsx

@@ -0,0 +1,34 @@
+import { Button, Heading, Text } from 'react-email'
+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="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-6 text-base text-gray-700">
+        Your SMTP settings work: this email reached your inbox.
+      </Text>
+      <Button
+        href="https://example.com"
+        className="bg-brand rounded-md px-5 py-3 text-center text-sm font-medium text-white"
+      >
+        Test Button
+      </Button>
+    </EmailLayout>
+  )
+}
+
+TestEmail.PreviewProps = {
+  name: 'Alex Morgan'
+} satisfies TestEmailProps

package/template/saas-starter/src/emails/welcome.tsx

@@ -0,0 +1,37 @@
+import { Heading, Text } from 'react-email'
+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) {
+  return (
+    <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}
+      </Heading>
+
+      <Text className="mb-4 text-base text-gray-700">Hi {userName},</Text>
+
+      <Text className="mb-4 text-base text-gray-700">
+        Your account is ready. Sign in any time with the email address this
+        message was sent to.
+      </Text>
+    </EmailLayout>
+  )
+}
+
+WelcomeEmail.PreviewProps = {
+  userName: 'Alex Morgan',
+  companyName: siteConfig.name
+} satisfies WelcomeEmailProps

package/template/saas-starter/src/env.ts

@@ -0,0 +1,66 @@
+import { createEnv } from '@t3-oss/env-nextjs'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    APP_ENV: z.enum(['development', 'staging', 'production']),
+    ANALYZE: z.string().optional(),
+    DATABASE_URL: z.url(),
+    BETTER_AUTH_URL: z.url(),
+    BETTER_AUTH_SECRET: z.string(),
+    BETTER_AUTH_GITHUB_ID: z.string(),
+    BETTER_AUTH_GITHUB_SECRET: z.string(),
+    BETTER_AUTH_GOOGLE_ID: z.string(),
+    BETTER_AUTH_GOOGLE_SECRET: z.string(),
+    EMAIL_SERVER_USER: z.string(),
+    EMAIL_SERVER_PASSWORD: z.string(),
+    EMAIL_SERVER_HOST: z.string(),
+    EMAIL_SERVER_PORT: z.coerce.number().int().min(1).max(65535),
+    EMAIL_FROM: z.email(),
+    STRIPE_SECRET_KEY: z.string(),
+    STRIPE_WEBHOOK_SECRET: z.string(),
+    STRIPE_PRICE_PRO_MONTHLY: z.string(),
+    STRIPE_PRICE_PRO_ANNUAL: z.string(),
+    STRIPE_PRICE_ULTIMATE_MONTHLY: z.string(),
+    STRIPE_PRICE_ULTIMATE_ANNUAL: z.string(),
+    STRIPE_PORTAL_CONFIGURATION_ID: z.string(),
+    R2_ACCOUNT_ID: z.string().optional(),
+    R2_ACCESS_KEY_ID: z.string().optional(),
+    R2_SECRET_ACCESS_KEY: z.string().optional(),
+    R2_BUCKET_NAME: z.string().optional(),
+    R2_PUBLIC_URL: z.url().optional()
+  },
+
+  client: {},
+
+  runtimeEnv: {
+    APP_ENV: process.env.APP_ENV,
+    ANALYZE: process.env.ANALYZE,
+    DATABASE_URL: process.env.DATABASE_URL,
+    BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,
+    BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
+    BETTER_AUTH_GITHUB_ID: process.env.BETTER_AUTH_GITHUB_ID,
+    BETTER_AUTH_GITHUB_SECRET: process.env.BETTER_AUTH_GITHUB_SECRET,
+    BETTER_AUTH_GOOGLE_ID: process.env.BETTER_AUTH_GOOGLE_ID,
+    BETTER_AUTH_GOOGLE_SECRET: process.env.BETTER_AUTH_GOOGLE_SECRET,
+    EMAIL_SERVER_USER: process.env.EMAIL_SERVER_USER,
+    EMAIL_SERVER_PASSWORD: process.env.EMAIL_SERVER_PASSWORD,
+    EMAIL_SERVER_HOST: process.env.EMAIL_SERVER_HOST,
+    EMAIL_SERVER_PORT: process.env.EMAIL_SERVER_PORT,
+    EMAIL_FROM: process.env.EMAIL_FROM,
+    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+    STRIPE_WEBHOOK_SECRET: process.env.STRIPE_WEBHOOK_SECRET,
+    STRIPE_PRICE_PRO_MONTHLY: process.env.STRIPE_PRICE_PRO_MONTHLY,
+    STRIPE_PRICE_PRO_ANNUAL: process.env.STRIPE_PRICE_PRO_ANNUAL,
+    STRIPE_PRICE_ULTIMATE_MONTHLY: process.env.STRIPE_PRICE_ULTIMATE_MONTHLY,
+    STRIPE_PRICE_ULTIMATE_ANNUAL: process.env.STRIPE_PRICE_ULTIMATE_ANNUAL,
+    STRIPE_PORTAL_CONFIGURATION_ID: process.env.STRIPE_PORTAL_CONFIGURATION_ID,
+    R2_ACCOUNT_ID: process.env.R2_ACCOUNT_ID,
+    R2_ACCESS_KEY_ID: process.env.R2_ACCESS_KEY_ID,
+    R2_SECRET_ACCESS_KEY: process.env.R2_SECRET_ACCESS_KEY,
+    R2_BUCKET_NAME: process.env.R2_BUCKET_NAME,
+    R2_PUBLIC_URL: process.env.R2_PUBLIC_URL
+  },
+
+  emptyStringAsUndefined: true
+})

package/template/saas-starter/src/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from 'react'
+
+const MOBILE_BREAKPOINT = 768
+
+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
+}
+
+function getServerSnapshot() {
+  return false
+}
+
+export function useIsMobile() {
+  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}

package/template/saas-starter/src/instrumentation.ts

@@ -0,0 +1,44 @@
+import { SpanStatusCode } from '@opentelemetry/api'
+import {
+  ConsoleSpanExporter,
+  ReadableSpan,
+  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
+    // 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)
+    }
+  }
+}
+
+/**
+ * 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: siteConfig.name,
+    spanProcessors: [new SmartSamplingSpanProcessor(new ConsoleSpanExporter())]
+  })
+}

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

@@ -0,0 +1,63 @@
+/**
+ * @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[] = [
+  {
+    label: 'Overview',
+    items: [
+      {
+        title: 'Dashboard',
+        url: '/admin',
+        exact: true,
+        icon: Home
+      }
+    ]
+  },
+  {
+    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',
+        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/saas-starter/src/lib/app-navigation.ts

@@ -0,0 +1,63 @@
+import { CreditCard, Home, Settings, Ticket, Users } from 'lucide-react'
+import { SidebarNavGroup } from '~/components/navigation-sidebar'
+import { isManagerRole } from './rbac'
+
+/**
+ * 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
+): SidebarNavGroup[] {
+  const groups: SidebarNavGroup[] = [
+    {
+      label: 'Workspace',
+      items: [
+        {
+          title: 'Dashboard',
+          url: `/app/${organizationId}/dashboard`,
+          icon: Home
+        }
+      ]
+    }
+  ]
+
+  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

@@ -0,0 +1,34 @@
+'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,
+  lastLoginMethodClient,
+  magicLinkClient,
+  organizationClient
+} 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
+} = createAuthClient({
+  plugins: [
+    inferAdditionalFields<typeof auth>(),
+    magicLinkClient(),
+    adminClient({ ac, roles }),
+    organizationClient(),
+    lastLoginMethodClient()
+  ]
+})

package/template/saas-starter/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 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'
+
+/**
+ * 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