@amirulabu/create-recurring-rabbit-app 0.0.0-alpha

package/templates/default/src/lib/env.ts

@@ -0,0 +1,119 @@
+/**
+ * Environment variable validation and configuration module.
+ *
+ * This module uses the @t3-oss/env-core library to provide type-safe environment variable
+ * validation at runtime. It ensures all required environment variables are present and
+ * properly typed before the application starts, failing fast with clear error messages
+ * if validation fails.
+ *
+ * Key patterns and conventions:
+ * - Environment variables are loaded from .env.local file (not .env) to prevent
+ *   accidentally committing secrets
+ * - Server-side variables use default names, client-side use PUBLIC_ prefix
+ * - Zod schemas provide both runtime validation and TypeScript type inference
+ * - Empty strings are treated as undefined (emptyStringAsUndefined: true) to allow
+ *   optional variables to be unset without empty string handling
+ *
+ * Security considerations:
+ * - BETTER_AUTH_SECRET must be at least 32 characters for JWT signing security
+ * - RESEND_API_KEY is loaded from environment, never hardcoded
+ * - DATABASE_URL is optional to support different database configurations
+ * - Skip validation flag (SKIP_ENV_VALIDATION) exists for CI/CD environments
+ *   where not all env vars may be needed, but should NOT be used in production
+ * - Client-side variables (PUBLIC_ prefix) are exposed to browser - never put
+ *   secrets there
+ *
+ * Configuration decisions:
+ * - Using @t3-oss/env-core instead of direct process.env access for:
+ *   - Type safety with inferred TypeScript types
+ *   - Runtime validation that fails fast on startup
+ *   - Clear error messages when validation fails
+ *   - Separation of server and client environment variables
+ * - .env.local path prevents git commits of secrets (already in .gitignore)
+ * - Better-auth requires at least 32 characters for secrets to match
+ *   cryptographic best practices for JWT signing keys
+ */
+
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+import dotenv from 'dotenv'
+
+dotenv.config({ path: '.env.local' })
+
+/**
+ * Type-safe environment configuration object.
+ *
+ * This object is the single source of truth for all environment variables in the
+ * application. Access environment variables through this object to ensure type
+ * safety and proper validation.
+ *
+ * Server variables are only available on the server (Node.js runtime).
+ * Client variables (prefixed with PUBLIC_) are available in the browser.
+ *
+ * @example
+ * // Server-side usage
+ * const dbUrl = env.DATABASE_URL
+ * const secret = env.BETTER_AUTH_SECRET
+ *
+ * // Client-side usage (e.g., in React components)
+ * const appUrl = env.PUBLIC_APP_URL
+ *
+ * @throws {Error} If validation fails on startup (unless SKIP_ENV_VALIDATION=true)
+ */
+export const env = createEnv({
+  server: {
+    /**
+     * Database connection URL.
+     * Optional to support different database configurations or test environments
+     * without a database connection.
+     */
+    DATABASE_URL: z.string().url().optional(),
+    /**
+     * Secret key for Better-Auth JWT signing and session encryption.
+     * Must be at least 32 characters to ensure sufficient entropy for
+     * cryptographic operations. This is critical for security - never commit
+     * this value to version control.
+     */
+    BETTER_AUTH_SECRET: z.string().min(32),
+    /**
+     * Base URL for the application, used by Better-Auth for OAuth redirects
+     * and callback URLs. Must be a valid URL including protocol (http:// or https://).
+     */
+    BETTER_AUTH_URL: z.string().url(),
+    /**
+     * API key for Resend email service. Used to send transactional emails.
+     * Required for email verification and password reset functionality.
+     * Never expose this value to the client.
+     */
+    RESEND_API_KEY: z.string().min(1),
+    /**
+     * Node environment that determines application behavior.
+     * - development: Enables debug logging, detailed error messages
+     * - test: Optimized for running test suites
+     * - production: Optimized for performance, minimal logging
+     */
+    NODE_ENV: z
+      .enum(['development', 'test', 'production'])
+      .default('development'),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {
+    /**
+     * Public base URL for the application.
+     * Available on both server and client. Used for:
+     * - Constructing absolute URLs in the browser
+     * - OAuth redirect URLs
+     * - Email verification and password reset links
+     * Note: Never include sensitive data in PUBLIC_ prefixed variables.
+     */
+    PUBLIC_APP_URL: z.string().url(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+  /**
+   * Allows skipping validation in CI/CD environments where not all env vars
+   * are needed (e.g., running type checking without database).
+   * SECURITY WARNING: Never use this in production deployment.
+   */
+  skipValidation: process.env.SKIP_ENV_VALIDATION === 'true',
+})

package/templates/default/src/lib/hydration-timing.ts

@@ -0,0 +1,289 @@
+/**
+ * React Server Components (RSC) hydration timing module.
+ *
+ * This module provides utilities to measure and track the time it takes for React
+ * components to hydrate on the client side. Hydration is the process where React
+ * attaches event listeners to server-rendered HTML and makes the page interactive.
+ *
+ * Key patterns and conventions:
+ * - Timing is measured using performance.now() for sub-millisecond precision
+ * - Component names are used as keys to group measurements
+ * - Slow hydration warnings are only shown in development mode
+ * - Metrics are stored globally (hydrationTimings object) for easy access
+ * - Metrics persist across page renders for cumulative analysis
+ *
+ * Performance implications:
+ * - Negligible overhead: performance.now() calls take sub-microsecond time
+ * - No blocking operations: All timing is synchronous and non-blocking
+ * - Memory usage: Grows with the number of unique components measured
+ * - Development-only warnings: Console.warn is skipped in production
+ *
+ * Configuration decisions:
+ * - SLOW_HYDRATION_THRESHOLD of 100ms is chosen because:
+ *   - React's target time to hydration is <100ms for optimal user experience
+ *   - Users perceive delays >100ms as perceptible lag
+ *   - Helps identify components that cause blocking JavaScript execution
+ * - Global storage (hydrationTimings object) simplifies access but means:
+ *   - Metrics accumulate indefinitely during the session
+ *   - Reset should be called between test runs or when starting fresh
+ * - Component name as key (not component instance) aggregates timing:
+ *   - All instances of the same component share timing data
+ *   - Useful for identifying slow component types, not specific instances
+ *
+ * Use cases:
+ * - Development: Identify components that cause slow hydration
+ * - Performance optimization: Target the slowest components for optimization
+ * - Testing: Assert that hydration times meet performance budgets
+ * - Production monitoring: Can be integrated with analytics (with sampling)
+ *
+ * How hydration timing works:
+ * 1. Server renders HTML and sends to client
+ * 2. Client receives HTML and renders it immediately
+ * 3. React downloads JavaScript and starts hydration
+ * 4. For each component, markHydrationStart() is called
+ * 5. Component processes and attaches event listeners
+ * 6. markHydrationEnd() is called with duration calculated
+ * 7. Slow hydrations (>100ms) are warned in development
+ *
+ * @example
+ * // In a component
+ * import { markHydrationStart, markHydrationEnd } from '@/lib/hydration-timing'
+ *
+ * export function MyComponent() {
+ *   if (typeof window !== 'undefined') {
+ *     markHydrationStart('MyComponent')
+ *   }
+ *   // ... component logic
+ *   useEffect(() => {
+ *     if (typeof window !== 'undefined') {
+ *       markHydrationEnd('MyComponent')
+ *     }
+ *   }, [])
+ * }
+ */
+
+/**
+ * Global storage for hydration timing metrics.
+ *
+ * This object stores both start times and durations for measured components.
+ * The naming convention is:
+ * - `${componentName}_start`: The timestamp when hydration started
+ * - `${componentName}_duration`: The calculated hydration duration in ms
+ *
+ * Why use a plain object instead of a Map:
+ * - Simpler to debug (visible in console as object)
+ * - Easy to serialize for analytics if needed
+ * - Sufficient for the expected number of components (<100 typically)
+ *
+ * Memory usage: O(n) where n is the number of unique components measured.
+ * Each entry stores a number (8 bytes) plus object overhead.
+ *
+ * Note: This object is mutable and accessed globally. Use the helper
+ * functions (markHydrationStart, markHydrationEnd) to interact with it
+ * to maintain consistent behavior.
+ */
+export const hydrationTimings: Record<string, number> = {}
+
+/**
+ * Marks the start of hydration for a component.
+ *
+ * This function records the current timestamp for a component, which will be
+ * used later to calculate the hydration duration when markHydrationEnd is called.
+ *
+ * Performance characteristics:
+ * - Time complexity: O(1)
+ * - Space complexity: O(1) per call (one number stored)
+ * - Overhead: Negligible (<1 microsecond)
+ *
+ * When to call:
+ * - At the very beginning of component hydration
+ * - Before any component logic that might block
+ * - Only on the client (check typeof window !== 'undefined')
+ * - For top-level components that significantly affect perceived performance
+ *
+ * Best practices:
+ * - Use consistent component names across your application
+ * - Avoid measuring every component (too much noise)
+ * - Focus on heavy components: lists, forms, data-heavy displays
+ * - Pair with markHydrationEnd to calculate duration
+ *
+ * @param componentName - The name of the component being hydrated.
+ *                        Use a consistent naming convention (e.g., PascalCase).
+ *                        This is used as the key for storing metrics.
+ *
+ * @example
+ * if (typeof window !== 'undefined') {
+ *   markHydrationStart('UserDashboard')
+ * }
+ */
+export function markHydrationStart(componentName: string) {
+  hydrationTimings[`${componentName}_start`] = performance.now()
+}
+
+/**
+ * Marks the end of hydration for a component and logs slow hydrations.
+ *
+ * This function calculates the hydration duration by comparing the current time
+ * with the previously recorded start time. If the component took longer than
+ * 100ms to hydrate, a warning is logged in development mode.
+ *
+ * Performance characteristics:
+ * - Time complexity: O(1)
+ * - Overhead: Negligible (<1 microsecond for calculation)
+ * - Console.warn is the only potentially expensive operation, but only in
+ *   development and only for slow hydrations
+ *
+ * Slow hydration threshold (100ms):
+ * - Chosen based on user perception research: 100ms is the threshold for
+ *   "instant" feeling
+ * - React's hydration should ideally complete within this window
+ * - Components exceeding this are candidates for optimization
+ *
+ * When to call:
+ * - After component logic completes
+ * - After all child components have hydrated
+ * - In a useEffect or similar to ensure it runs after render
+ * - Only on the client (check typeof window !== 'undefined')
+ *
+ * Edge cases:
+ * - If start time doesn't exist (markHydrationStart not called), this
+ *   function does nothing silently
+ * - Multiple calls for the same component: Each call calculates duration
+ *   from the most recent start time
+ *
+ * @param componentName - The name of the component that finished hydrating.
+ *                        Must match the name passed to markHydrationStart.
+ *
+ * @example
+ * useEffect(() => {
+ *   if (typeof window !== 'undefined') {
+ *     markHydrationEnd('UserDashboard')
+ *   }
+ * }, [])
+ */
+export function markHydrationEnd(componentName: string) {
+  const startTime = hydrationTimings[`${componentName}_start`]
+  if (startTime) {
+    const duration = performance.now() - startTime
+    hydrationTimings[`${componentName}_duration`] = duration
+
+    /**
+     * Warn about slow hydrations in development only.
+     *
+     * Why development-only:
+     * - Console.warn in production can impact performance
+     * - Production users don't need to see warnings
+     * - Production monitoring should use analytics tools instead
+     *
+     * Why 100ms threshold:
+     * - Based on research: users perceive delays >100ms as "laggy"
+     * - React's target: <100ms to interactivity
+     * - Helps identify blocking components for optimization
+     */
+    if (import.meta.env.DEV && duration > 100) {
+      console.warn(
+        `[Slow Hydration] ${componentName}: ${duration.toFixed(2)}ms`
+      )
+    }
+  }
+}
+
+/**
+ * Retrieves all hydration metrics, sorted by duration descending.
+ *
+ * This function returns an array of component hydration durations, sorted
+ * so the slowest components appear first. This is useful for identifying
+ * which components have the biggest impact on page load performance.
+ *
+ * Performance characteristics:
+ * - Time complexity: O(n) for iterating through keys + O(n log n) for sorting
+ * - Space complexity: O(n) for the results array
+ * - Typically very fast for realistic numbers of components (<100)
+ *
+ * Return format:
+ * - Array of objects with component name and duration
+ * - Sorted by duration descending (slowest first)
+ * - Only includes components that have completed hydration
+ * - Durations are in milliseconds (raw values, not averaged)
+ *
+ * Use cases:
+ * - Development: Identify the slowest components to optimize
+ * - Testing: Assert that component hydration meets performance budgets
+ * - Analytics: Send hydration metrics to performance monitoring services
+ * - Debugging: Understand which components contribute most to TTI (Time to Interactive)
+ *
+ * Limitations:
+ * - Includes all historical measurements (accumulates during session)
+ * - Call resetHydrationMetrics() to start fresh
+ * - Averages are not calculated; returns individual durations
+ *
+ * @returns Array of hydration metrics, each containing:
+ *          - component: The component name (without _duration suffix)
+ *          - duration: The hydration time in milliseconds
+ *
+ * @example
+ * const metrics = getHydrationMetrics()
+ * console.log('Top 3 slowest components:')
+ * metrics.slice(0, 3).forEach(({ component, duration }) => {
+ *   console.log(`${component}: ${duration.toFixed(2)}ms`)
+ * })
+ */
+export function getHydrationMetrics() {
+  const metrics: Array<{ component: string; duration: number }> = []
+
+  /**
+   * Iterate through all recorded timings.
+   *
+   * Object.keys iteration order is not guaranteed, so we sort afterwards.
+   * We only include entries ending in '_duration' to exclude start times.
+   */
+  Object.keys(hydrationTimings).forEach((key) => {
+    if (key.endsWith('_duration')) {
+      const component = key.replace('_duration', '')
+      const duration = hydrationTimings[key] || 0
+      metrics.push({ component, duration })
+    }
+  })
+
+  /**
+   * Sort by duration descending.
+   *
+   * This puts the slowest components first, which is useful for:
+   * - Prioritizing optimization efforts
+   * - Quickly identifying the biggest performance bottlenecks
+   * - Focusing on components that have the most impact on TTI
+   */
+  return metrics.sort((a, b) => b.duration - a.duration)
+}
+
+/**
+ * Clears all recorded hydration metrics.
+ *
+ * This function removes all start times and durations from the global
+ * hydrationTimings object. Use this to start fresh measurements.
+ *
+ * Performance characteristics:
+ * - Time complexity: O(n) where n is the number of recorded metrics
+ * - Memory: Immediately eligible for garbage collection (subject to V8 GC)
+ *
+ * When to call:
+ * - Between test runs to ensure clean state
+ * - When starting a new performance measurement session
+ * - Before running specific performance tests
+ * - After gathering metrics for analysis
+ *
+ * CAUTION: This removes all metrics, including those from previous components.
+ * If you need to preserve certain metrics, copy them before calling this function.
+ *
+ * @example
+ * // Reset before a performance test
+ * resetHydrationMetrics()
+ * await runPageLoad()
+ * const metrics = getHydrationMetrics()
+ * console.log('Hydration times after reset:', metrics)
+ */
+export function resetHydrationMetrics() {
+  Object.keys(hydrationTimings).forEach((key) => {
+    delete hydrationTimings[key]
+  })
+}