create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/db/index.ts

@@ -0,0 +1,60 @@
+import 'server-only'
+
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import { env } from '~/env'
+import * as relations from './relations'
+import * as schema from './schema'
+
+// In development, Next.js hot-reloading can re-evaluate modules frequently.
+// Keep a single postgres-js client on `globalThis` to avoid opening multiple
+// database connections during local development.
+const globalForDb = globalThis as unknown as {
+  client?: ReturnType<typeof postgres>
+}
+
+// Prefer the cached client (dev) and fall back to creating a new one.
+// `prepare: false` disables prepared statements, which transaction-mode
+// poolers such as PgBouncer and Neon's pooler reject.
+const client =
+  globalForDb.client ??
+  postgres(env.DATABASE_URL, {
+    prepare: false,
+    // For neon.tech postgres db, as its serverless
+    ...(env.DATABASE_URL.includes('neon.tech')
+      ? {
+          max: 5,
+          idle_timeout: 30, // seconds an idle connection is kept before closing
+          max_lifetime: 60 * 5, // recycle a connection after 5 minutes
+          connect_timeout: 60 // seconds to wait for a connection (Neon cold start)
+        }
+      : {})
+  })
+
+// Only cache the client outside production to avoid unexpected cross-request
+// state retention in long-lived production processes.
+if (env.APP_ENV !== 'production') globalForDb.client = client
+
+/**
+ * Drizzle ORM database client for PostgreSQL.
+ *
+ * Backed by a postgres-js client configured via `env.DATABASE_URL`, and wired
+ * up with schema + relations so you get typed query helpers.
+ *
+ * Use this instance throughout the app for all database operations.
+ *
+ * @example
+ * const users = await db.query.usersTable.findMany()
+ * const newUser = await db.insert(usersTable).values({ email: 'user@example.com' })
+ *
+ * @example
+ * await db.transaction(async (tx) => {
+ *   await tx.insert(usersTable).values({ email: 'user@example.com' })
+ * })
+ */
+export const db = drizzle(client, {
+  schema: { ...schema, ...relations }
+})
+
+/** The transaction client type passed into `db.transaction(async (tx) => ...)`. */
+export type DbTx = Parameters<Parameters<(typeof db)['transaction']>[0]>[0]

package/template/saas-starter/src/db/relations.ts

@@ -0,0 +1,112 @@
+import { relations } from 'drizzle-orm'
+import {
+  accountsTable,
+  feedbacksTable,
+  invitationsTable,
+  membersTable,
+  organizationSubscriptionsTable,
+  organizationsTable,
+  sessionsTable,
+  supportTicketMessagesTable,
+  supportTicketsTable,
+  usersTable
+} from './schema'
+
+export const userRelations = relations(usersTable, ({ many }) => ({
+  sessions: many(sessionsTable),
+  accounts: many(accountsTable),
+  members: many(membersTable),
+  invitations: many(invitationsTable)
+}))
+
+export const sessionRelations = relations(sessionsTable, ({ one }) => ({
+  user: one(usersTable, {
+    fields: [sessionsTable.userId],
+    references: [usersTable.id]
+  })
+}))
+
+export const accountRelations = relations(accountsTable, ({ one }) => ({
+  user: one(usersTable, {
+    fields: [accountsTable.userId],
+    references: [usersTable.id]
+  })
+}))
+
+export const organizationRelations = relations(
+  organizationsTable,
+  ({ many, one }) => ({
+    subscription: one(organizationSubscriptionsTable, {
+      fields: [organizationsTable.id],
+      references: [organizationSubscriptionsTable.organizationId]
+    }),
+    members: many(membersTable),
+    invitations: many(invitationsTable),
+    supportTickets: many(supportTicketsTable),
+    feedbacks: many(feedbacksTable)
+  })
+)
+
+export const memberRelations = relations(membersTable, ({ one }) => ({
+  organization: one(organizationsTable, {
+    fields: [membersTable.organizationId],
+    references: [organizationsTable.id]
+  }),
+  user: one(usersTable, {
+    fields: [membersTable.userId],
+    references: [usersTable.id]
+  })
+}))
+
+export const invitationRelations = relations(invitationsTable, ({ one }) => ({
+  organization: one(organizationsTable, {
+    fields: [invitationsTable.organizationId],
+    references: [organizationsTable.id]
+  }),
+  inviter: one(usersTable, {
+    fields: [invitationsTable.inviterId],
+    references: [usersTable.id]
+  })
+}))
+
+export const organizationSubscriptionRelations = relations(
+  organizationSubscriptionsTable,
+  ({ one }) => ({
+    organization: one(organizationsTable, {
+      fields: [organizationSubscriptionsTable.organizationId],
+      references: [organizationsTable.id]
+    })
+  })
+)
+
+export const supportTicketRelations = relations(
+  supportTicketsTable,
+  ({ one, many }) => ({
+    organization: one(organizationsTable, {
+      fields: [supportTicketsTable.organizationId],
+      references: [organizationsTable.id]
+    }),
+    user: one(usersTable, {
+      fields: [supportTicketsTable.userId],
+      references: [usersTable.id]
+    }),
+    messages: many(supportTicketMessagesTable)
+  })
+)
+
+export const supportTicketMessageRelations = relations(
+  supportTicketMessagesTable,
+  ({ one }) => ({
+    ticket: one(supportTicketsTable, {
+      fields: [supportTicketMessagesTable.ticketId],
+      references: [supportTicketsTable.id]
+    })
+  })
+)
+
+export const feedbackRelations = relations(feedbacksTable, ({ one }) => ({
+  organization: one(organizationsTable, {
+    fields: [feedbacksTable.organizationId],
+    references: [organizationsTable.id]
+  })
+}))

package/template/saas-starter/src/db/schema.ts

@@ -0,0 +1,342 @@
+/**
+ * @fileoverview Drizzle table definitions.
+ *
+ * Enums live in `./enums.ts` and reusable column helpers in `./common.ts`.
+ * Every foreign key leads an index and declares an explicit `onDelete`;
+ * `tests/db/fk-indexes.test.ts` enforces both.
+ */
+import { sql } from 'drizzle-orm'
+import {
+  boolean,
+  check,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  uniqueIndex,
+  varchar
+} from 'drizzle-orm/pg-core'
+import { commonFieldDefs, nonNegativeCheck } from './common'
+import {
+  organizationSubscriptionIntervalEnum,
+  organizationSubscriptionPlanEnum,
+  organizationSubscriptionStatusEnum,
+  supportTicketPriorityEnum,
+  supportTicketStatusEnum
+} from './enums'
+
+export * from './enums'
+
+// ─── Auth (Better Auth) ─────────────────────────────────────────
+
+export const usersTable = pgTable(
+  'users',
+  {
+    id: commonFieldDefs.id('user'),
+    name: text('name').notNull(),
+    email: text('email').notNull().unique(),
+    emailVerified: boolean('email_verified').default(false).notNull(),
+    image: text('image'),
+    role: text('role'),
+    banned: boolean('banned').default(false),
+    banReason: text('ban_reason'),
+    banExpires: commonFieldDefs.date('ban_expires'),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.createdAt), index().on(table.role)]
+)
+
+export const sessionsTable = pgTable(
+  'sessions',
+  {
+    id: commonFieldDefs.id('session'),
+    expiresAt: commonFieldDefs.date('expires_at').notNull(),
+    token: text('token').notNull().unique(),
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+    userId: text('user_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    impersonatedBy: text('impersonated_by'),
+    activeOrganizationId: text('active_organization_id'),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.userId)]
+)
+
+export const accountsTable = pgTable(
+  'accounts',
+  {
+    id: commonFieldDefs.id('account'),
+    accountId: text('account_id').notNull(),
+    providerId: text('provider_id').notNull(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    accessToken: text('access_token'),
+    refreshToken: text('refresh_token'),
+    idToken: text('id_token'),
+    accessTokenExpiresAt: commonFieldDefs.date('access_token_expires_at'),
+    refreshTokenExpiresAt: commonFieldDefs.date('refresh_token_expires_at'),
+    scope: text('scope'),
+    password: text('password'),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.userId)]
+)
+
+export const verificationsTable = pgTable(
+  'verifications',
+  {
+    id: commonFieldDefs.id('verification'),
+    identifier: text('identifier').notNull(),
+    value: text('value').notNull(),
+    expiresAt: commonFieldDefs.date('expires_at').notNull(),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.identifier)]
+)
+
+// ─── Organizations (Better Auth) ────────────────────────────────
+
+export const organizationsTable = pgTable('organizations', {
+  id: commonFieldDefs.id('organization'),
+  name: text('name').notNull(),
+  slug: text('slug').notNull().unique(),
+  logo: text('logo'),
+  metadata: text('metadata'),
+  ...commonFieldDefs.dates
+})
+
+export const membersTable = pgTable(
+  'members',
+  {
+    id: commonFieldDefs.id('member'),
+    organizationId: text('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
+    userId: text('user_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    role: text('role').notNull(),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    uniqueIndex().on(table.organizationId, table.userId),
+    index().on(table.userId)
+  ]
+)
+
+export const invitationsTable = pgTable(
+  'invitations',
+  {
+    id: commonFieldDefs.id('invitation'),
+    organizationId: text('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
+    email: text('email').notNull(),
+    role: text('role'),
+    status: text('status').default('pending').notNull(),
+    expiresAt: commonFieldDefs.date('expires_at'),
+    inviterId: text('inviter_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.organizationId),
+    index().on(table.email),
+    index().on(table.inviterId),
+    uniqueIndex()
+      .on(table.organizationId, table.email)
+      .where(sql`${table.status} = 'pending'`)
+  ]
+)
+
+// ─── Billing ────────────────────────────────────────────────────
+
+export const organizationSubscriptionsTable = pgTable(
+  'organization_subscriptions',
+  {
+    id: commonFieldDefs.id('organization_subscription'),
+    organizationId: text('organization_id')
+      .notNull()
+      .unique()
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
+    plan: organizationSubscriptionPlanEnum('plan').notNull().default('free'),
+    status: organizationSubscriptionStatusEnum('status')
+      .notNull()
+      .default('free'),
+    interval: organizationSubscriptionIntervalEnum('interval'),
+    billingEmail: text('billing_email'),
+    stripeCustomerId: text('stripe_customer_id').unique(),
+    stripeSubscriptionId: text('stripe_subscription_id').unique(),
+    hasUsedTrial: boolean('has_used_trial').notNull().default(false),
+    trialEndsAt: commonFieldDefs.date('trial_ends_at'),
+    currentPeriodEnd: commonFieldDefs.date('current_period_end'),
+    cancelAtPeriodEnd: boolean('cancel_at_period_end').notNull().default(false),
+    ...commonFieldDefs.dates
+  }
+)
+
+/** One row per Stripe event, so a redelivered webhook is processed once. */
+export const stripeWebhooksEventsTable = pgTable('stripe_webhooks_events', {
+  id: text('id').primaryKey(),
+  type: text('type').notNull(),
+  receivedAt: commonFieldDefs.date('received_at').notNull().defaultNow(),
+  processed: boolean('processed').notNull().default(false),
+  processedAt: commonFieldDefs.date('processed_at'),
+  error: text('error'),
+  // Stored only when processing fails, for replay and debugging.
+  payload: jsonb('payload')
+})
+
+// ─── Support ────────────────────────────────────────────────────
+
+/** Single-row counter behind `TICKET-000001` numbers; see `scripts/setup-db.ts`. */
+export const supportTicketCounterTable = pgTable(
+  'support_ticket_counter',
+  {
+    id: integer('id').primaryKey().default(1),
+    counter: integer('counter').notNull().default(0)
+  },
+  table => [
+    nonNegativeCheck('support_ticket_counter_counter_non_negative', [
+      table.counter
+    ])
+  ]
+)
+
+/**
+ * A ticket with an `organizationId` belongs to that organization's managers.
+ * A ticket without one is an account ticket, visible only to its author.
+ * Platform admins see both.
+ */
+export const supportTicketsTable = pgTable(
+  'support_tickets',
+  {
+    id: commonFieldDefs.id('support_ticket'),
+    // The database fills this in from a trigger; see `scripts/setup-db.ts`.
+    ticketNumber: varchar('ticket_number')
+      .notNull()
+      .unique()
+      .$defaultFn(() => ''),
+    organizationId: varchar('organization_id').references(
+      () => organizationsTable.id,
+      { onDelete: 'set null' }
+    ),
+    userId: varchar('user_id').references(() => usersTable.id, {
+      onDelete: 'set null'
+    }),
+    subject: varchar('subject').notNull(),
+    status: supportTicketStatusEnum('status').notNull().default('open'),
+    priority: supportTicketPriorityEnum('priority'),
+    resolvedAt: commonFieldDefs.date('resolved_at'),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.userId, table.createdAt),
+    index().on(table.organizationId, table.createdAt),
+    index().on(table.status),
+    index().on(table.priority)
+  ]
+)
+
+export const supportTicketMessagesTable = pgTable(
+  'support_ticket_messages',
+  {
+    id: commonFieldDefs.id('support_ticket_message'),
+    ticketId: varchar('ticket_id')
+      .notNull()
+      .references(() => supportTicketsTable.id, { onDelete: 'cascade' }),
+    userId: varchar('user_id').references(() => usersTable.id, {
+      onDelete: 'set null'
+    }),
+    message: text('message').notNull(),
+    /** True when the support team wrote it, even if the author is also a customer. */
+    isAdmin: boolean('is_admin').notNull().default(false),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.ticketId), index().on(table.userId)]
+)
+
+export const feedbacksTable = pgTable(
+  'feedbacks',
+  {
+    id: commonFieldDefs.id('feedback'),
+    userId: varchar('user_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    organizationId: varchar('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
+    rating: integer('rating').notNull(),
+    comment: text('comment'),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.userId),
+    index().on(table.organizationId, table.createdAt),
+    index().on(table.createdAt),
+    check('feedbacks_rating_range', sql`${table.rating} BETWEEN 1 AND 5`)
+  ]
+)
+
+export const contactLeadsTable = pgTable(
+  'contact_leads',
+  {
+    id: commonFieldDefs.id('contact_lead'),
+    name: varchar('name').notNull(),
+    email: varchar('email').notNull(),
+    phone: varchar('phone'),
+    subject: varchar('subject').notNull(),
+    message: text('message').notNull(),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.createdAt)]
+)
+
+// ─── Uploads ────────────────────────────────────────────────────
+
+export const fileUploadsTable = pgTable(
+  'file_uploads',
+  {
+    id: commonFieldDefs.id('file_upload'),
+    // Object key, such as uploads/organizations/<organizationId>/<file>.jpg
+    key: text('key').notNull().unique(),
+    originalName: varchar('original_name').notNull(),
+    mimeType: varchar('mime_type').notNull(),
+    // In bytes
+    size: integer('size').notNull(),
+    isTemp: boolean('is_temp').notNull().default(true),
+    uploadedBy: varchar('uploaded_by').references(() => usersTable.id, {
+      onDelete: 'set null'
+    }),
+    // `restrict` forces organization deletion to remove the R2 objects first;
+    // see `deleteOrganizationUploads`.
+    organizationId: varchar('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'restrict' }),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.uploadedBy),
+    index().on(table.organizationId),
+    index().on(table.isTemp, table.createdAt),
+    nonNegativeCheck('file_uploads_size_non_negative', [table.size])
+  ]
+)
+
+// ─── Seed ───────────────────────────────────────────────────────
+
+/**
+ * Singleton marker for a successful `seedDatabase` run. While
+ * {@link SEED_RUN_MARKER_ID} exists, the seed script does nothing.
+ */
+export const SEED_RUN_MARKER_ID = 'seed_run_default'
+
+export const seedRunsTable = pgTable('seed_runs', {
+  id: varchar('id').primaryKey(),
+  ...commonFieldDefs.dates
+})

package/template/saas-starter/src/emails/components/email-layout.tsx

@@ -0,0 +1,79 @@
+/**
+ * @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,
+  Html,
+  pixelBasedPreset,
+  Preview,
+  Section,
+  Tailwind,
+  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
+}
+
+export default function EmailLayout({
+  previewText,
+  companyName,
+  children
+}: EmailLayoutProps) {
+  return (
+    <Html>
+      <Head />
+      <Preview>{previewText}</Preview>
+      <Tailwind
+        config={{
+          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">
+            <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>
+
+            <Section className="px-8 py-6">{children}</Section>
+
+            <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. Replies to this address are not
+                read.
+              </Text>
+            </Section>
+          </Container>
+        </Body>
+      </Tailwind>
+    </Html>
+  )
+}

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

@@ -0,0 +1,69 @@
+import { Button, Heading, Text } from 'react-email'
+import EmailLayout from '~/emails/components/email-layout'
+import { INVITATION_EXPIRES_IN_DAYS } from '~/lib/constants'
+import { roleArticle } from '~/lib/rbac'
+import { siteConfig } from '~/lib/siteConfig'
+
+export interface InvitationEmailProps {
+  inviteUrl: string
+  organizationName: string
+  inviterName: string
+  role: string
+  companyName: string
+}
+
+/** Invitation to join an organization, sent by the Better Auth organization plugin. */
+export default function InvitationEmail({
+  inviteUrl,
+  organizationName,
+  inviterName,
+  role,
+  companyName
+}: InvitationEmailProps) {
+  return (
+    <EmailLayout
+      previewText={`${inviterName} invited you to join ${organizationName}`}
+      companyName={companyName}
+    >
+      <Heading className="mb-4 text-2xl font-bold text-gray-900">
+        You&apos;re Invited to Join {organizationName}
+      </Heading>
+
+      <Text className="mb-4 text-base text-gray-700">
+        {inviterName} invited you to join <strong>{organizationName}</strong> on{' '}
+        {companyName} as {roleArticle(role)}.
+      </Text>
+
+      <Text className="mb-4 text-base text-gray-700">
+        Select the button below to accept. You&apos;ll sign in with this email
+        address first.
+      </Text>
+
+      <Button
+        href={inviteUrl}
+        className="bg-brand mb-4 rounded-lg px-6 py-3 text-center text-base font-semibold text-white no-underline"
+      >
+        Accept Invitation
+      </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">{inviteUrl}</Text>
+
+      <Text className="text-sm text-gray-500">
+        This invitation expires in {INVITATION_EXPIRES_IN_DAYS} days. If you
+        weren&apos;t expecting it, you can ignore this email.
+      </Text>
+    </EmailLayout>
+  )
+}
+
+InvitationEmail.PreviewProps = {
+  inviteUrl: 'https://example.com/accept-invitation/your_invitation_id_here',
+  organizationName: 'Acme Inc.',
+  inviterName: 'Alex Morgan',
+  role: 'member',
+  companyName: siteConfig.name
+} satisfies InvitationEmailProps