create-ej-app 26.0.0 → 27.0.0

package/template/nextjs/tests/db/fk-indexes.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+
+/**
+ * Postgres does not index foreign key columns automatically. Without an index,
+ * every cascade or SET NULL from the parent side sequentially scans the child
+ * table while holding row locks, so deleting one user can stall the
+ * platform.
+ *
+ * This finds every FK whose leading column is not the leading column of any
+ * index, which is exactly the shape that degrades.
+ */
+const UNINDEXED_FOREIGN_KEYS = sql`
+  SELECT
+    c.conrelid::regclass::text AS table_name,
+    a.attname::text AS column_name
+  FROM pg_constraint c
+  JOIN pg_attribute a
+    ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+  WHERE c.contype = 'f'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM pg_index i
+      WHERE i.indrelid = c.conrelid
+        AND i.indkey[0] = c.conkey[1]
+    )
+  ORDER BY 1, 2
+`
+
+/** postgres-js returns a row array; PGlite returns `{ rows }`. */
+const toRows = <T>(result: unknown): T[] =>
+  Array.isArray(result)
+    ? (result as T[])
+    : ((result as { rows: T[] }).rows ?? [])
+
+describe('foreign key indexing', () => {
+  test('every foreign key column leads an index', async () => {
+    const rows = toRows<{ table_name: string; column_name: string }>(
+      await db.execute(UNINDEXED_FOREIGN_KEYS)
+    )
+
+    expect(rows.map(r => `${r.table_name}.${r.column_name}`)).toEqual([])
+  })
+
+  test('every foreign key declares an explicit delete rule', async () => {
+    const rows = toRows<{ table_name: string; constraint_name: string }>(
+      await db.execute(sql`
+        SELECT
+          c.conrelid::regclass::text AS table_name,
+          c.conname::text AS constraint_name
+        FROM pg_constraint c
+        WHERE c.contype = 'f' AND c.confdeltype = 'a'
+        ORDER BY 1, 2
+      `)
+    )
+
+    // confdeltype 'a' is NO ACTION, which is what an omitted onDelete leaves
+    // behind. Every FK should say cascade, set null, or restrict on purpose.
+    expect(rows.map(r => `${r.table_name}.${r.constraint_name}`)).toEqual([])
+  })
+})

package/template/nextjs/tests/db/seed.test.ts

@@ -0,0 +1,49 @@
+import { PGlite } from '@electric-sql/pglite'
+import { describe, expect, test } from 'bun:test'
+import { pushSchema } from 'drizzle-kit/api'
+import { drizzle } from 'drizzle-orm/pglite'
+import * as relations from '~/db/relations'
+import * as schema from '~/db/schema'
+import { seedDatabase } from '~/scripts/seed'
+
+/**
+ * The seed writes straight through the schema, around Zod, so it exercises
+ * constraints and foreign keys against realistic data.
+ *
+ * It runs on its own PGlite instance: seeded rows would otherwise leak into
+ * every other suite in the same worker and break their counts.
+ */
+describe('seed script', () => {
+  test('applies cleanly once, then skips', async () => {
+    // Same Emscripten proc_exit side effect as tests/setup/pglite-db.ts.
+    const exitCodeBeforePglite = process.exitCode
+
+    const client = new PGlite()
+    const db = drizzle({ client, schema: { ...schema, ...relations } })
+
+    const { apply, hasDataLoss } = await pushSchema(
+      schema,
+      db as unknown as Parameters<typeof pushSchema>[1]
+    )
+    expect(hasDataLoss).toBe(false)
+    await apply()
+
+    const seed = () =>
+      seedDatabase(db as unknown as Parameters<typeof seedDatabase>[0])
+
+    expect((await seed()).skipped).toBe(false)
+
+    const users = await db.select().from(schema.usersTable)
+    expect(users.map(user => user.role).sort()).toEqual(['superadmin', 'user'])
+
+    expect((await seed()).skipped).toBe(true)
+    expect(await db.select().from(schema.usersTable)).toHaveLength(2)
+
+    if (process.exitCode === 99) {
+      process.exitCode =
+        exitCodeBeforePglite !== undefined && exitCodeBeforePglite !== 99
+          ? exitCodeBeforePglite
+          : 0
+    }
+  }, 120_000)
+})

package/template/nextjs/tests/helpers/action.ts

@@ -0,0 +1,71 @@
+import { expect } from 'bun:test'
+import { UNEXPECTED_ERROR_MESSAGE } from '~/lib/safe-action'
+
+type ActionResult = {
+  data?: unknown
+  serverError?: string
+  validationErrors?: unknown
+}
+
+const MASKED = UNEXPECTED_ERROR_MESSAGE
+
+export function expectData<T>(
+  result: ActionResult | undefined
+): asserts result is { data: T } {
+  if (!result) throw new Error('Expected action result, got undefined')
+  if (result.serverError) {
+    throw new Error(`Expected success, got serverError: ${result.serverError}`)
+  }
+  if (result.validationErrors) {
+    throw new Error(
+      `Expected success, got validationErrors: ${JSON.stringify(result.validationErrors)}`
+    )
+  }
+  if (result.data === undefined) {
+    throw new Error('Expected action data, got undefined')
+  }
+}
+
+/** Action returned null/undefined data (some actions swallow errors). */
+export function expectNoData(result: ActionResult | undefined) {
+  expect(result?.data ?? null).toBeNull()
+}
+
+/** Action was rejected by its input schema, before any handler ran. */
+export function expectValidationError(result: ActionResult | undefined) {
+  if (!result?.validationErrors) {
+    throw new Error(
+      `Expected validationErrors, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  return result.validationErrors
+}
+
+/**
+ * Action failed with a serverError.
+ * next-safe-action can mask thrown Error messages as a generic string.
+ * In that case, this helper only asserts that a failure occurred.
+ */
+export function expectServerError(
+  result: ActionResult | undefined,
+  messageIncludes?: string | RegExp
+) {
+  if (!result?.serverError) {
+    throw new Error(
+      `Expected serverError, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  if (
+    messageIncludes &&
+    result.serverError.toLowerCase() !== MASKED.toLowerCase()
+  ) {
+    if (typeof messageIncludes === 'string') {
+      expect(result.serverError.toLowerCase()).toContain(
+        messageIncludes.toLowerCase()
+      )
+    } else {
+      expect(result.serverError).toMatch(messageIncludes)
+    }
+  }
+  return result.serverError
+}

package/template/nextjs/tests/helpers/fixtures.ts

@@ -0,0 +1,78 @@
+/**
+ * Throwaway DB fixtures and auth helpers for Bun tests.
+ *
+ *   const fx = new Fixtures()
+ *   afterEach(() => fx.cleanup())
+ *   const admin = await fx.platformUser('superadmin')
+ *   await asUser(admin, () => someAction(...))
+ */
+import { createId } from '@paralleldrive/cuid2'
+import { inArray } from 'drizzle-orm'
+import { db } from '~/db'
+import { usersTable } from '~/db/schema'
+import { runWithAuthSession } from '../setup/preload'
+
+type User = typeof usersTable.$inferSelect
+
+const uid = () =>
+  `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
+
+export class Fixtures {
+  private userIds: string[] = []
+
+  async user(
+    overrides: { name?: string; email?: string; role?: string | null } = {}
+  ): Promise<User> {
+    const s = uid()
+    const [row] = await db
+      .insert(usersTable)
+      .values({
+        id: `user_${createId()}`,
+        name: overrides.name ?? `Test User ${s}`,
+        email: overrides.email ?? `test+${s}@example.com`,
+        emailVerified: true,
+        role: overrides.role ?? 'user'
+      })
+      .returning()
+    if (!row) throw new Error('Failed to create test user')
+    this.userIds.push(row.id)
+    return row
+  }
+
+  /** Platform user for admin-panel tests. */
+  platformUser(role: 'admin' | 'superadmin') {
+    return this.user({ name: `Platform ${role}`, role })
+  }
+
+  async cleanup() {
+    if (this.userIds.length) {
+      await db.delete(usersTable).where(inArray(usersTable.id, this.userIds))
+      this.userIds = []
+    }
+  }
+}
+
+/** Runs `fn` with `getAuthSession()` returning this user. */
+export function asUser<T>(user: User, fn: () => Promise<T>): Promise<T> {
+  const isSuperAdmin = user.role === 'superadmin'
+  const isAdmin = user.role === 'admin' || isSuperAdmin
+  return runWithAuthSession(
+    {
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+        role: user.role
+      },
+      session: { id: `test_session_${user.id}`, userId: user.id },
+      isAdmin,
+      isSuperAdmin
+    },
+    fn
+  )
+}
+
+/** Runs `fn` signed out. */
+export function asAnonymous<T>(fn: () => Promise<T>): Promise<T> {
+  return runWithAuthSession(null, fn)
+}

package/template/nextjs/tests/helpers/index.ts

@@ -0,0 +1,2 @@
+export * from './action'
+export * from './fixtures'

package/template/nextjs/tests/lib/callback-url.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test'
+import { sanitizeCallbackUrl } from '~/lib/callback-url'
+
+// Everything sanitizeCallbackUrl rejects must be something a browser would
+// resolve off-origin, so each case is checked against URL resolution too.
+const APP_ORIGIN = 'https://app.example.com'
+
+const resolvesOffOrigin = (value: string) =>
+  new URL(value, APP_ORIGIN).origin !== APP_ORIGIN
+
+describe('sanitizeCallbackUrl', () => {
+  test('keeps same-origin paths, including query and hash', () => {
+    expect(sanitizeCallbackUrl('/app')).toBe('/app')
+    expect(sanitizeCallbackUrl('/accept-invitation/inv_abc123')).toBe(
+      '/accept-invitation/inv_abc123'
+    )
+    expect(sanitizeCallbackUrl('/app/orders?status=open#top')).toBe(
+      '/app/orders?status=open#top'
+    )
+  })
+
+  test('rejects values that are not a path', () => {
+    expect(sanitizeCallbackUrl(undefined)).toBeNull()
+    expect(sanitizeCallbackUrl(['/app', '/admin'])).toBeNull()
+    expect(sanitizeCallbackUrl('app')).toBeNull()
+    expect(sanitizeCallbackUrl('https://evil.com')).toBeNull()
+  })
+
+  test('rejects the backslash and double-slash escapes out of the origin', () => {
+    for (const value of ['//evil.com', '/\\evil.com', '/\\\\evil.com']) {
+      expect(resolvesOffOrigin(value)).toBe(true)
+      expect(sanitizeCallbackUrl(value)).toBeNull()
+    }
+  })
+
+  test('rejects tabs and newlines, which URL parsing strips before resolving', () => {
+    for (const value of ['/\t/evil.com', '/\n/evil.com', '/\r/evil.com']) {
+      expect(resolvesOffOrigin(value)).toBe(true)
+      expect(sanitizeCallbackUrl(value)).toBeNull()
+    }
+  })
+
+  test('leaves lookalike hosts on the app origin instead of rejecting them', () => {
+    // These stay same-origin, so they are safe to honour.
+    expect(sanitizeCallbackUrl('/@evil.com')).toBe('/@evil.com')
+    expect(sanitizeCallbackUrl('/%5Cevil.com')).toBe('/%5Cevil.com')
+  })
+})

package/template/nextjs/tests/lib/client-server-boundary.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Guard: `'use client'` modules must not import server runtime, secrets, or
+ * the database directly. Transitive imports leak too, but this test only reads
+ * each client file's own imports, so review what a new import pulls in.
+ */
+import { describe, expect, test } from 'bun:test'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+const SRC = path.resolve(import.meta.dir, '../../src')
+
+/**
+ * Import paths that must never appear in a `'use client'` module. Add every
+ * new server-only lib here.
+ */
+const FORBIDDEN_IMPORT_RE =
+  /from\s+['"](~\/db(?:\/(?:schema|enums|relations|common|index))?|~\/env|~\/lib\/(?:auth|safe-action|email-service|nodemailer)|server-only|drizzle-orm(?:\/[^'"]*)?)['"]/
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    if (name === 'node_modules' || name.startsWith('.')) continue
+    const full = path.join(dir, name)
+    if (statSync(full).isDirectory()) walk(full, out)
+    else if (/\.(ts|tsx)$/.test(name)) out.push(full)
+  }
+  return out
+}
+
+describe('client / server boundary', () => {
+  test('no use-client file imports server runtime or db modules', () => {
+    const violations: string[] = []
+
+    for (const file of walk(SRC)) {
+      const source = readFileSync(file, 'utf8')
+      if (
+        !source.includes("'use client'") &&
+        !source.includes('"use client"')
+      ) {
+        continue
+      }
+
+      for (const [index, line] of source.split('\n').entries()) {
+        // Type-only imports are erased, but they are banned too so a later
+        // value import is harder to slip in.
+        if (!FORBIDDEN_IMPORT_RE.test(line)) continue
+        // Explicit client-safe siblings
+        if (line.includes('auth-client')) continue
+        if (line.includes('safe-action-client')) continue
+
+        const rel = path.relative(SRC, file)
+        violations.push(`${rel}:${index + 1}: ${line.trim()}`)
+      }
+    }
+
+    expect(violations).toEqual([])
+  })
+})

package/template/nextjs/tests/lib/errors.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test'
+import { isUniqueViolation } from '~/lib/errors'
+
+describe('postgres error codes', () => {
+  test('an error whose cause points back at itself is not a match and does not hang', () => {
+    const error: { message: string; cause?: unknown } = { message: 'loop' }
+    error.cause = error
+    expect(isUniqueViolation(error)).toBe(false)
+  })
+})

package/template/nextjs/tests/lib/search.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test'
+import { escapeLikePattern, likeContains } from '~/lib/search'
+
+describe('escapeLikePattern', () => {
+  test('escapes LIKE wildcards and the escape character', () => {
+    expect(escapeLikePattern('%')).toBe('\\%')
+    expect(escapeLikePattern('_')).toBe('\\_')
+    expect(escapeLikePattern('\\')).toBe('\\\\')
+    expect(escapeLikePattern('100%_off\\sale')).toBe('100\\%\\_off\\\\sale')
+  })
+
+  test('leaves ordinary search text unchanged', () => {
+    expect(escapeLikePattern('Quarterly report')).toBe('Quarterly report')
+  })
+})
+
+describe('likeContains', () => {
+  test('wraps an escaped pattern for contains matching', () => {
+    expect(likeContains('report')).toBe('%report%')
+    expect(likeContains('%')).toBe('%\\%%')
+    expect(likeContains('_')).toBe('%\\_%')
+  })
+})

package/template/nextjs/tests/setup/pglite-db.ts

@@ -0,0 +1,63 @@
+/**
+ * In-memory Postgres for Bun tests via Electric PGlite (WASM).
+ *
+ * One instance per Bun worker process:
+ *   1. Start PGlite
+ *   2. pushSchema from Drizzle table definitions
+ */
+import { PGlite } from '@electric-sql/pglite'
+import { pushSchema } from 'drizzle-kit/api'
+import { drizzle, type PgliteDatabase } from 'drizzle-orm/pglite'
+import * as relations from '~/db/relations'
+import * as schema from '~/db/schema'
+
+const fullSchema = { ...schema, ...relations }
+
+type TestDatabase = PgliteDatabase<typeof fullSchema>
+
+let initPromise: Promise<TestDatabase> | null = null
+
+async function bootstrap(): Promise<TestDatabase> {
+  // PGlite's Emscripten runtime sets process.exitCode to 99 via proc_exit on
+  // the first WASM query. bun test then exits with that code even when every
+  // assertion passed. Snapshot first, restore only the spurious 99, and leave
+  // any real non-zero code alone.
+  const exitCodeBeforePglite = process.exitCode
+
+  const client = new PGlite()
+  const db = drizzle({ client, schema: fullSchema })
+
+  const { apply, warnings, hasDataLoss } = await pushSchema(
+    schema,
+    db as unknown as Parameters<typeof pushSchema>[1]
+  )
+  if (warnings.length) {
+    console.warn('[pglite] schema push warnings:', warnings)
+  }
+  if (hasDataLoss) {
+    throw new Error(
+      '[pglite] schema push reported data loss on a fresh database. Aborting.'
+    )
+  }
+  await apply()
+
+  if (process.exitCode === 99) {
+    process.exitCode =
+      exitCodeBeforePglite !== undefined && exitCodeBeforePglite !== 99
+        ? exitCodeBeforePglite
+        : 0
+  }
+
+  return db
+}
+
+/**
+ * Idempotent: first call boots PGlite and the schema; later calls return the same db.
+ * Safe to await from preload (once per worker).
+ */
+export function initPgliteDatabase(): Promise<TestDatabase> {
+  if (!initPromise) {
+    initPromise = bootstrap()
+  }
+  return initPromise
+}

package/template/nextjs/tests/setup/preload.ts

@@ -0,0 +1,95 @@
+/**
+ * Bun test preload (runs before every test file and worker).
+ *
+ * - In-memory PGlite Postgres (WASM) through a `~/db` mock
+ * - `react.cache` becomes identity
+ * - `getAuthSession` reads an AsyncLocalStorage (parallel-safe)
+ *
+ * Set `TEST_DATABASE=postgres` to use the real `DATABASE_URL` instead.
+ */
+import { mock } from 'bun:test'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+// Bun does not set the `react-server` export condition, so the real
+// `server-only` package throws. Next.js client builds still fail on it.
+mock.module('server-only', () => ({}))
+
+// `start()` needs the Workflow runtime. Tests only need fire-and-forget
+// side effects such as emails to no-op.
+mock.module('workflow/api', () => ({
+  start: async () => ({ runId: 'test-workflow-run' })
+}))
+
+// ---------------------------------------------------------------------------
+// Database: PGlite (default) or real Postgres
+// ---------------------------------------------------------------------------
+
+process.env.TEST_DATABASE ??= 'pglite'
+
+if (process.env.TEST_DATABASE === 'pglite') {
+  // ~/env requires a URL even though PGlite never connects to it.
+  process.env.DATABASE_URL ??= 'postgres://pglite.local/test'
+
+  const { initPgliteDatabase } = await import('./pglite-db')
+  const dbModule = { db: await initPgliteDatabase() }
+
+  mock.module('~/db', () => dbModule)
+  mock.module(
+    path.resolve(import.meta.dir, '../../src/db/index.ts'),
+    () => dbModule
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Auth and request headers
+// ---------------------------------------------------------------------------
+
+type MockAuthSession = {
+  user: { id: string; email: string; name: string; role?: string | null }
+  session: { id: string; userId: string; impersonatedBy?: string | null }
+  isAdmin: boolean
+  isSuperAdmin: boolean
+}
+
+const authAls = new AsyncLocalStorage<MockAuthSession | null>()
+
+/** Runs `fn` with `getAuthSession()` returning `session`. */
+export function runWithAuthSession<T>(
+  session: MockAuthSession | null,
+  fn: () => Promise<T>
+): Promise<T> {
+  return authAls.run(session, fn)
+}
+
+const require = createRequire(import.meta.url)
+const React = require('react') as typeof import('react')
+
+mock.module('react', () => ({
+  ...React,
+  default: React,
+  cache: <T extends (...args: never[]) => unknown>(fn: T) => fn
+}))
+
+const authModuleMock = {
+  getAuthSession: async () => authAls.getStore() ?? null,
+  auth: null as unknown
+}
+
+mock.module('~/lib/auth', () => authModuleMock)
+mock.module(
+  path.resolve(import.meta.dir, '../../src/lib/auth.ts'),
+  () => authModuleMock
+)
+
+mock.module('next/headers', () => ({
+  headers: async () => new Headers(),
+  cookies: async () => ({
+    get: () => undefined,
+    getAll: () => [],
+    has: () => false,
+    set: () => {},
+    delete: () => {}
+  })
+}))

package/template/nextjs/tsconfig.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "target": "ES2017",
     "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "types": ["bun"],
     "allowJs": true,
     "checkJs": true,
     "skipLibCheck": true,

package/template/saas-starter/.dockerignore

@@ -1,3 +1,4 @@
+.git
 node_modules
 .next
 out

package/template/saas-starter/.env.example

@@ -1,23 +1,23 @@
-APP_ENV="production"
+APP_ENV="development"
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
 BETTER_AUTH_URL="http://localhost:3000"
-BETTER_AUTH_SECRET="secret"
-BETTER_AUTH_GITHUB_ID="github_id"
-BETTER_AUTH_GITHUB_SECRET="github_secret"
-BETTER_AUTH_GOOGLE_ID="google_id"
-BETTER_AUTH_GOOGLE_SECRET="google_secret"
-EMAIL_SERVER_USER="username"
-EMAIL_SERVER_PASSWORD="password"
+BETTER_AUTH_SECRET="your_better_auth_secret_here"
+BETTER_AUTH_GITHUB_ID="your_github_client_id_here"
+BETTER_AUTH_GITHUB_SECRET="your_github_client_secret_here"
+BETTER_AUTH_GOOGLE_ID="your_google_client_id_here"
+BETTER_AUTH_GOOGLE_SECRET="your_google_client_secret_here"
+EMAIL_SERVER_USER="your_smtp_username_here"
+EMAIL_SERVER_PASSWORD="your_smtp_password_here"
 EMAIL_SERVER_HOST="smtp.example.com"
 EMAIL_SERVER_PORT="465"
 EMAIL_FROM="no-reply@example.com"
-STRIPE_SECRET_KEY="sk_test_xxxxxxxxxx"
-STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxx"
-STRIPE_PRICE_PRO_MONTHLY="price_xxxxxxxxxx"
-STRIPE_PRICE_PRO_ANNUAL="price_xxxxxxxxxx"
-STRIPE_PRICE_ULTIMATE_MONTHLY="price_xxxxxxxxxx"
-STRIPE_PRICE_ULTIMATE_ANNUAL="price_xxxxxxxxxx"
-STRIPE_PORTAL_CONFIGURATION_ID="bpc_xxxxxxxxxx"
+STRIPE_SECRET_KEY="your_stripe_secret_key_here"
+STRIPE_WEBHOOK_SECRET="your_stripe_webhook_secret_here"
+STRIPE_PRICE_PRO_MONTHLY="your_pro_monthly_price_id_here"
+STRIPE_PRICE_PRO_ANNUAL="your_pro_annual_price_id_here"
+STRIPE_PRICE_ULTIMATE_MONTHLY="your_ultimate_monthly_price_id_here"
+STRIPE_PRICE_ULTIMATE_ANNUAL="your_ultimate_annual_price_id_here"
+STRIPE_PORTAL_CONFIGURATION_ID="your_portal_configuration_id_here"
 R2_ACCOUNT_ID=""
 R2_ACCESS_KEY_ID=""
 R2_SECRET_ACCESS_KEY=""